Shiroa

https://myriad-dreamin.github.io/shiroa/
Admin
Shiroa is a tool for creating modern online books and documentation in pure Typst, providing...
Tokens:43,573
Snippets:412
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize and serve a book with shiroa

Source: https://myriad-dreamin.github.io/shiroa/paged/guide/get-started.html

Initializes a new book directory, changes into it, and starts a local webserver that builds and serves the book. Run these commands in order after installing the shiroa CLI.

```bash
shiroa init my-first-book
```

```bash
cd my-first-book
```

```bash
shiroa serve
```

--------------------------------

### Import and apply project show rule in chapter

Source: https://myriad-dreamin.github.io/shiroa/theme/builtin.html

Two renderings of the same chapter file that imports a project show rule from template.typ and applies it with the title "Getting Started". The first uses a plain heading; the second uses bold formatting on the heading and chapter content. Both are shown as alternatives in the source.

```typst
#import "template.typ": project
#show: project.with(title: "Getting Started")
= Getting Started
Chapter content.

```

```typst
#import "template.typ": project
#show: project.with(title: "Getting Started")
**=**** ****Getting Started**
Chapter content.

```

--------------------------------

### Serve the book locally with shiroa serve

Source: https://myriad-dreamin.github.io/shiroa/guide/get-started.html

Builds the book and starts a local webserver for previewing.

```bash
shiroa serve

```

--------------------------------

### Example book.typ summary content

Source: https://myriad-dreamin.github.io/shiroa/paged/format/book-meta.html

A complete example of a book summary configuration.

```typst
#prefix-chapter("introduction.typ")[Introduction]
= User Guide
- #chapter("guide/installation.typ")[Installation]
- #chapter("guide/get-started.typ")[Get Started]
- #chapter("guide/faq.typ")[Frequently Asked Questions]
- #chapter(none)[Further reading]
= Reference Guide
- #chapter("cli/main.typ")[Command Line Tool]
- #chapter("cli/init.typ")[init]
- #chapter("cli/build.typ")[build]
- #chapter("cli/serve.typ")[serve]
- #chapter("format/main.typ")[Format]
- #chapter("format/book.typ")[book.typ]
- #chapter("format/book-meta.typ")[Book Metadata]
- #chapter(none)[Draft chapter]
- #chapter("format/build-meta.typ")[Build Metadata]
- #chapter("supports.typ")[Typst Support]
- #chapter("supports/package.typ")[Package API]
- #chapter("supports/book-description.typ")[Book Description]
- #chapter("supports/targets.typ")[Rendering Targets and Inputs]
- #chapter("supports/metadata.typ")[Reading Metadata]
- #chapter("supports/content.typ")[Content Helpers]
- #chapter("supports/cross-ref.typ")[Cross Reference]
- #chapter("supports/cross-ref-sample.typ")[Cross Reference Sample]
- #chapter("supports/embed-html.typ")[Embed Sanitized HTML Elements]
- #chapter("supports/multimedia.typ")[Multimedia components]
- #chapter("supports/render-test.typ")[Rendering Tests]
- #chapter("supports/theme.typ")[Theme]
- #chapter("theme/builtin.typ")[Built-in Themes]
- #chapter("format/theme.typ")[Custom Theme]
- #chapter(none)[For developers]
```

--------------------------------

### Build all components from source

Source: https://myriad-dreamin.github.io/shiroa/guide/installation.html

Clones the repository, initializes submodules, builds the project, and optionally installs the CLI globally. Requires pnpm and Rust.

```bash
git clone https://github.com/Myriad-Dreamin/shiroa.git
git submodule update --recursive --init
cargo run --bin shiroa-build
_#__ optional: install it globally_
cargo install --path ./cli
```

```bash
git clone https://github.com/Myriad-Dreamin/shiroa.git
git submodule update --recursive --init
cargo run --bin shiroa-build
# optional: install it globally
cargo install --path ./cli
```

--------------------------------

### Start the default serve server

Source: https://myriad-dreamin.github.io/shiroa/cli/serve.html

Runs `shiroa serve` to preview the book in the current working directory at the default address `127.0.0.1:25520`. This command is for testing HTML output, not for production serving.

```bash
shiroa serve
```

--------------------------------

### Query and map book metadata with get-book-meta (duplicate)

Source: https://myriad-dreamin.github.io/shiroa/format/theme.html

This is a duplicate of the previous example provided in the source documentation.

```Typst
// Compile this example with Typst's HTML target.
#import "@preview/shiroa:0.4.0": get-book-meta
#let book-site-title(meta) = {
  if type(meta) == array {
    meta = meta.first()
  }
  if meta == none {
    ""
  } else if "raw-title" in meta {
    if meta.raw-title == none { "" } else { meta.raw-title }
  } else if "title" in meta {
    if type(meta.title) == str {
      meta.title
    } else {
      meta.title.content
    }
  } else {
    ""
  }
}
#let site-title() = get-book-meta(mapper: book-site-title)
#html.elem("header", context site-title())
```

--------------------------------

### Build shiroa from source and install globally

Source: https://myriad-dreamin.github.io/shiroa/paged/guide/installation.html

Builds all shiroa components from source. Requires cargo, Rust 1.88+, and pnpm. After global installation, uninstall with 'cargo uninstall shiroa' and ensure the Cargo bin directory is in your PATH.

```bash
git clone https://github.com/Myriad-Dreamin/shiroa.git
git submodule update --recursive --init
cargo run --bin shiroa-build
# optional: install it globally
cargo install --path ./cli
```

--------------------------------

### build-meta example

Source: https://myriad-dreamin.github.io/shiroa/format/book.html

Sets the destination directory for the generated book output. When dest-dir is set to ../dist, shiroa outputs to parent/dist relative to the book.typ file.

```typst
#build-meta(
  dest-dir: "../dist",
)
```

```typst
#build-meta(
  dest-dir: "../dist",
)
```

--------------------------------

### Create a chapter file

Source: https://myriad-dreamin.github.io/shiroa/guide/get-started.html

A minimal chapter file starting with a level 1 heading and placeholder content.

```typst
= My First Chapter
Fill out your content here.

```

--------------------------------

### Complete theme skeleton

Source: https://myriad-dreamin.github.io/shiroa/paged/format/theme.html

A comprehensive example combining native HTML, dynamic paged content, metadata, and custom assets.

```typst
#import "@preview/shiroa:0.4.0": (
html-support,
is-html-target,
paged-load-trampoline,
plain-text,
prepare-description,
x-target,
)
#import html-support: inline-assets, supports-html-internal
#import supports-html-internal: dyn-svg-support

#let base-css = ```css
body {
margin: 0;
font-family: system-ui, sans-serif;
}

.layout {
max-width: 72rem;
margin-inline: auto;
padding: 2rem;
}
```

#let my-theme(
book,
body,
title: "",
description: auto,
plain-body: auto,
extra-assets: (),
) = {
if not is-html-target() {
return body
}

let plain-body = if plain-body == auto { body } else { plain-body }
let description = prepare-description(
description,
plain-body: plain-body,
)
let main = if x-target.starts-with("html-wrapper") {
paged-load-trampoline()
} else {
body
}

html.elem("html", {
html.elem("head", {
html.elem("meta", attrs: (charset: "utf-8"))
html.elem(
"meta",
attrs: (
name: "viewport",
content: "width=device-width, initial-scale=1.0",
),
)
html.elem("title", plain-text(title))
if description != none {
html.elem(
"meta",
attrs: (name: "description", content: description),
)
}
if x-target.starts-with("html-wrapper") {
dyn-svg-support()
}
inline-assets((base-css, ..extra-assets).join())
})

html.elem("body", {
book
html.elem("div", {
html.elem("header", html.elem("h1", title))
html.elem("main", main)

```

--------------------------------

### Basic book-meta structure

Source: https://myriad-dreamin.github.io/shiroa/format/book-meta.html

Example of a full book structure definition.

```Typst
#book-meta(
  summary: [
    #prefix-chapter("pre.typ")[Prefix Chapter]
    = User Guide
    - #chapter("1.typ", section: "1")[First Chapter]
        - #chapter("1.1.typ", section: "1.1")[First sub]
    - #chapter("2.typ", section: "1")[Second Chapter]
    #suffix-chapter("suf.typ")[Suffix Chapter]
  ],
)
```

```Typst
#book-meta(
  summary: [
    #prefix-chapter("pre.typ")[Prefix Chapter]
    **=**** ****User Guide**
    - #chapter("1.typ", section: "1")[First Chapter]
        - #chapter("1.1.typ", section: "1.1")[First sub]
    - #chapter("2.typ", section: "1")[Second Chapter]
    #suffix-chapter("suf.typ")[Suffix Chapter]
  ],
)
```

--------------------------------

### Apply theme from project show rule

Source: https://myriad-dreamin.github.io/shiroa/paged/format/theme.html

Shows how to apply the my-theme.typ theme from the project show rule using show: my-theme.with(). The call is installed before body is emitted, giving the theme both the original semantic body and the body after inner show rules.

```typst
// Compile this example with Typst's HTML target.
#import "my-theme.typ": my-theme

#let project(
  title: "",
  description: auto,
  body,
) = {
  show: my-theme.with(
    include "book.typ",
    title: title,
    description: description,
    plain-body: body,
  )

  body
}
```

--------------------------------

### Import and assert x-url-base

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/targets.html

Import x-url-base and assert it starts and ends with a slash. Use this value to prefix site-local links and assets when the book may be hosted below a path such as /project/.

```typst
#import "@preview/shiroa:0.4.0": x-url-base

#assert(x-url-base.starts-with("/") and x-url-base.ends-with("/"))
```

--------------------------------

### Configuring Extra Assets

Source: https://myriad-dreamin.github.io/shiroa/theme/builtin.html

Example of injecting custom CSS into the HTML head using the extra-assets parameter.

```typst
_// Compile this example with Typst's HTML target._
#import "@preview/shiroa-starlight:0.4.0": starlight
#let extra-css = ```css
.site-title {
  font-style: italic;
}
```
#let project(title: "", body) = {
  show: starlight.with(
    include "book.typ",
    title: title,
    plain-body: body,
    extra-assets: (extra-css,),
  )
  body
}
```

```typst
// Compile this example with Typst's HTML target.
#import "@preview/shiroa-starlight:0.4.0": starlight
#let extra-css = ```css
.site-title {
  font-style: italic;
}
```
#let project(title: "", body) = {
  show: starlight.with(
    include "book.typ",
    title: title,
    plain-body: body,
    extra-assets: (extra-css,),
  )
  body
}
```

--------------------------------

### Change the serve address (--addr)

Source: https://myriad-dreamin.github.io/shiroa/cli/serve.html

Specifies a custom address with `--addr` to override the default `127.0.0.1:25520`. The example serves the book at `127.0.0.1:8000`.

```bash
shiroa serve path/to/book --addr 127.0.0.1:8000
```

--------------------------------

### Import template in Typst

Source: https://myriad-dreamin.github.io/shiroa/cli/build.html

Example of accessing a template file using an absolute path in Typst after setting the root.

```typst
#import "/common/book-template.typ": *
```

--------------------------------

### x-url-base

Source: https://myriad-dreamin.github.io/shiroa/supports/targets.html

The normalized deployment prefix. It always starts and ends with '/'. Prefix site-local links and assets with it when the book can be hosted below a path.

```APIDOC
## x-url-base

### Description
The normalized deployment prefix. It always starts and ends with '/'. Prefix site-local links and assets with it when the book can be hosted below a path such as '/project/'.

### Usage
Import from @preview/shiroa:0.4.0 and use as a string constant.

### Example
#import "@preview/shiroa:0.4.0": x-url-base
#assert(x-url-base.starts-with("/") and x-url-base.ends-with("/"))

```

--------------------------------

### Complete Custom Theme Skeleton

Source: https://myriad-dreamin.github.io/shiroa/format/theme.html

A complete theme implementation using Typst that handles HTML targets, metadata, and layout. This example requires the Shiroa package version 0.4.0.

```typst
_// Compile this example with Typst's HTML target._
#import "@preview/shiroa:0.4.0": (
  html-support,
  is-html-target,
  paged-load-trampoline,
  plain-text,
  prepare-description,
  x-target,
)
#import html-support: inline-assets, supports-html-internal
#import supports-html-internal: dyn-svg-support
#let base-css = ```css
body {
  margin: 0;
  font-family: system-ui, sans-serif;
}
.layout {
  max-width: 72rem;
  margin-inline: auto;
  padding: 2rem;
}
```
#let my-theme(
  book,
  body,
  title: "",
  description: auto,
  plain-body: auto,
  extra-assets: (),
) = {
  if not is-html-target() {
    return body
  }
  let plain-body = if plain-body == auto { body } else { plain-body }
  let description = prepare-description(
    description,
    plain-body: plain-body,
  )
  let main = if x-target.starts-with("html-wrapper") {
    paged-load-trampoline()
  } else {
    body
  }
  html.elem("html", {
    html.elem("head", {
      html.elem("meta", attrs: (charset: "utf-8"))
      html.elem(
        "meta",
        attrs: (
          name: "viewport",
          content: "width=device-width, initial-scale=1.0",
        ),
      )
      html.elem("title", plain-text(title))
      if description != none {
        html.elem(
          "meta",
          attrs: (name: "description", content: description),
        )
      }
      if x-target.starts-with("html-wrapper") {
        dyn-svg-support()
      }
      inline-assets((base-css, ..extra-assets).join())
    })
    html.elem("body", {
      book
      html.elem("div", {
        html.elem("header", html.elem("h1", title))
        html.elem("main", main)
      }, attrs: (class: "layout"))
    })
  }, attrs: (lang: "en"))
}
#let project(title: "", description: auto, body) = {
  show: my-theme.with(
    include "book.typ",
    title: title,
    description: description,
    plain-body: body,
  )
  body
}
```

```typst
// Compile this example with Typst's HTML target.
#import "@preview/shiroa:0.4.0": (
  html-support,
  is-html-target,
  paged-load-trampoline,
  plain-text,
  prepare-description,
  x-target,
)
#import html-support: inline-assets, supports-html-internal
#import supports-html-internal: dyn-svg-support
#let base-css = ```css
body {
  margin: 0;
  font-family: system-ui, sans-serif;
}
.layout {
  max-width: 72rem;
  margin-inline: auto;
  padding: 2rem;
}
```
#let my-theme(
  book,
  body,
  title: "",
  description: auto,
  plain-body: auto,
  extra-assets: (),
) = {
  if not is-html-target() {
    return body
  }
  let plain-body = if plain-body == auto { body } else { plain-body }
  let description = prepare-description(
    description,
    plain-body: plain-body,
  )
  let main = if x-target.starts-with("html-wrapper") {
    paged-load-trampoline()
  } else {
    body
  }
  html.elem("html", {
    html.elem("head", {
      html.elem("meta", attrs: (charset: "utf-8"))
      html.elem(
        "meta",
        attrs: (
          name: "viewport",
          content: "width=device-width, initial-scale=1.0",
        ),
      )
      html.elem("title", plain-text(title))
      if description != none {
        html.elem(
          "meta",
          attrs: (name: "description", content: description),
        )
      }
      if x-target.starts-with("html-wrapper") {
        dyn-svg-support()
      }
      inline-assets((base-css, ..extra-assets).join())
    })
    html.elem("body", {
      book
      html.elem("div", {
        html.elem("header", html.elem("h1", title))
        html.elem("main", main)
      }, attrs: (class: "layout"))
    })
  }, attrs: (lang: "en"))
}
#let project(title: "", description: auto, body) = {
  show: my-theme.with(
    include "book.typ",
    title: title,
    description: description,
    plain-body: body,
  )
  body
}
```

--------------------------------

### Import and assert x-current

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/targets.html

Import x-current and assert it is either none or a string. Use it to get the current source path, or none outside a Shiroa page compilation, for highlighting the active chapter and expanding {path} in edit links.

```typst
#import "@preview/shiroa:0.4.0": x-current

#assert(x-current == none or type(x-current) == str)
```

--------------------------------

### Initialize a new book with shiroa init

Source: https://myriad-dreamin.github.io/shiroa/guide/get-started.html

Creates a new directory named my-first-book containing an empty book template.

```bash
shiroa init my-first-book

```

--------------------------------

### Initialize a book to a directory

Source: https://myriad-dreamin.github.io/shiroa/cli/init.html

Initializes a new book project in the specified directory and builds it.

```bash
shiroa init my-book/
shiroa build my-book/
```

--------------------------------

### Install shiroa via cargo

Source: https://myriad-dreamin.github.io/shiroa/guide/installation.html

Installs the shiroa CLI tool directly from the GitHub repository using cargo. Requires Rust version 1.88 or higher.

```bash
cargo install --git https://github.com/Myriad-Dreamin/shiroa --locked shiroa
```

--------------------------------

### Initialize and build a book to a directory

Source: https://myriad-dreamin.github.io/shiroa/paged/cli/init.html

The init command creates a new book directory and then builds it, so build options are available. The target directory must not already exist.

```bash
shiroa init my-book/
shiroa build my-book/

```

--------------------------------

### Initialize book.typ with book and book-meta

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/book-description.html

Use the book show rule to initialize the project and book-meta to define the title and summary.

```typst
#import "@preview/shiroa:0.4.0": *
#show: book

#book-meta(
title: "My Book",
summary: [],
)
```

--------------------------------

### Basic cross-link usage

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/cross-ref.html

Examples of using cross-link with and without a specific reference label.

```typst
#cross-link("/guide/get-started.typ")[Getting Started]
#cross-link(
"/guide/get-started.typ",
reference: <configuration>,
)[Configuration]
```

--------------------------------

### Initialize a book with a specific dest-dir

Source: https://myriad-dreamin.github.io/shiroa/cli/init.html

Sets a custom destination directory for the build output. The configuration is remembered in book.typ.

```bash
shiroa init --dest-dir ../dist my-book/
shiroa build my-book/ # remembered in book.typ
```

--------------------------------

### Layout and Language Attributes

Source: https://myriad-dreamin.github.io/shiroa/paged/format/theme.html

Example of setting layout and language attributes within a theme configuration.

```typst
}, attrs: (class: "layout"))  
})  
}, attrs: (lang: "en"))  
}
```

--------------------------------

### Import all and define book-meta in book.typ

Source: https://myriad-dreamin.github.io/shiroa/supports/package.html

Import all book-description helpers and set up a book.typ with a title and a summary that uses prefix-chapter and chapter to link to chapters.

```typst
#import "@preview/shiroa:0.4.0": *
#show: book
#book-meta(
  title: "My Book",
  summary: [
    #prefix-chapter("introduction.typ")[Introduction]
    = Guide
    - #chapter("guide/start.typ")[Getting Started]
  ],
)

```

--------------------------------

### Initialize a book with a specific typst workspace directory

Source: https://myriad-dreamin.github.io/shiroa/cli/init.html

Uses the --root flag to specify the typst workspace directory during initialization and build.

```bash
shiroa init --root . my-book/
shiroa build --root . my-book/
```

--------------------------------

### Serve without building first (--no-build)

Source: https://myriad-dreamin.github.io/shiroa/cli/serve.html

Uses the `--no-build` flag to serve the output directory without building the book first. This skips the default build step.

```bash
shiroa serve --no-build
```

--------------------------------

### Run build command

Source: https://myriad-dreamin.github.io/shiroa/paged/cli/build.html

Basic command to render the book in the current working directory.

```bash
shiroa build
```

--------------------------------

### Minimal book.typ

Source: https://myriad-dreamin.github.io/shiroa/paged/cli/init.html

Must provide a `book-meta` and include the shiroa preview package.

```typst
#import "@preview/shiroa:0.4.0": *
#show: book

#book-meta(
title: "My Book",
summary: [
= My Book
- #chapter("chapter1.typ", section: "1")[Chapter 1]
],
)
```

--------------------------------

### Initialize with custom dest-dir

Source: https://myriad-dreamin.github.io/shiroa/paged/cli/init.html

Use `--dest-dir ../dist` to set the build destination. The dest-dir is remembered in book.typ for subsequent builds.

```bash
shiroa init --dest-dir ../dist my-book/
shiroa build my-book/ # remembered in book.typ

```

--------------------------------

### Query and map book metadata with get-book-meta

Source: https://myriad-dreamin.github.io/shiroa/format/theme.html

This example demonstrates how to use get-book-meta with a custom mapper function to extract and return the site title for an HTML header element.

```Typst
_// Compile this example with Typst's HTML target._
#import "@preview/shiroa:0.4.0": get-book-meta
#let book-site-title(meta) = {
  if type(meta) == array {
    meta = meta.first()
  }
  if meta == none {
    ""
  } else if "raw-title" in meta {
    if meta.raw-title == none { "" } else { meta.raw-title }
  } else if "title" in meta {
    if type(meta.title) == str {
      meta.title
    } else {
      meta.title.content
    }
  } else {
    ""
  }
}
#let site-title() = get-book-meta(mapper: book-site-title)
#html.elem("header", context site-title())
```

--------------------------------

### Import and assert get-page-width

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/targets.html

Import get-page-width and page-width, then assert they are equal. Use get-page-width() in page templates to get the width selected by Shiroa for the current responsive layout.

```typst
#import "@preview/shiroa:0.4.0": get-page-width, page-width

#assert(get-page-width() == page-width)
```

--------------------------------

### Initialize with custom typst workspace root

Source: https://myriad-dreamin.github.io/shiroa/paged/cli/init.html

Use `--root .` to specify the current directory as the typst workspace root for both init and build.

```bash
shiroa init --root . my-book/
shiroa build --root . my-book/

```

--------------------------------

### Build the book with shiroa build

Source: https://myriad-dreamin.github.io/shiroa/guide/get-started.html

Builds the book into a directory named book containing HTML content, ready to be hosted on any web server.

```bash
shiroa build

```

--------------------------------

### Set root directory with --root

Source: https://myriad-dreamin.github.io/shiroa/paged/cli/build.html

Specifies the root directory for Typst source files. This example shows building a project while accessing a template file in a common directory.

```bash
shiroa build --root . book-project1
```

```typst
#import "/common/book-template.typ": *
```

--------------------------------

### Import the media module

Source: https://myriad-dreamin.github.io/shiroa/supports/embed-html.html

Imports the Shiroa media module as a namespace. This is the first step to use the media functions.

```typst
#import "@preview/shiroa:0.4.0": media
```

--------------------------------

### Configure book.typ with book and book-meta

Source: https://myriad-dreamin.github.io/shiroa/supports/book-description.html

The book function acts as a show rule for the root book.typ file, while book-meta stores project metadata for the CLI and themes.

```typst
#import "@preview/shiroa:0.4.0": *
#show: book
#book-meta(
  title: "My Book",
  summary: [],
)
```

--------------------------------

### book-meta example

Source: https://myriad-dreamin.github.io/shiroa/format/book.html

Defines the book's metadata: title, authors, and a summary that lists chapters and their hierarchy. The summary field is required and uses Typst functions like #prefix-chapter, #chapter, and #suffix-chapter.

```typst
#book-meta(
  title: "shiroa",
  authors: ("Myriad-Dreamin", "7mile"),
  summary: [ _// this field works like summary.md of mdbook_
    #prefix-chapter("pre.typ")[Prefix Chapter]
    = User Guide
    - #chapter("1.typ", section: "1")[First Chapter]
        - #chapter("1.1.typ", section: "1.1")[First sub]
    - #chapter("2.typ", section: "1")[Second Chapter]
    #suffix-chapter("suf.typ")[Suffix Chapter]
  ]
)
```

```typst
#book-meta(
  title: "shiroa",
  authors: ("Myriad-Dreamin", "7mile"),
  summary: [ // this field works like summary.md of mdbook
    #prefix-chapter("pre.typ")[Prefix Chapter]
    **=**** ****User Guide**
    - #chapter("1.typ", section: "1")[First Chapter]
        - #chapter("1.1.typ", section: "1.1")[First sub]
    - #chapter("2.typ", section: "1")[Second Chapter]
    #suffix-chapter("suf.typ")[Suffix Chapter]
  ]
)
```

--------------------------------

### Build with static-html mode

Source: https://myriad-dreamin.github.io/shiroa/guide/get-started.html

Builds the book using the experimental static-html mode, which exports the book as static HTML files using Typst v0.13.0's HTML export.

```bash
shiroa build --mode static-html

```

--------------------------------

### prepare-description: normalize page description for a theme

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/content.html

Use prepare-description to normalize a page description for a theme. none disables the description; a string is returned unchanged; auto extracts and trims plain-body, truncating it to limit clusters and appending ... when the limit is reached. The example shows assertions for none and auto with plain-body.

```typst
#import "@preview/shiroa:0.4.0": prepare-description

#assert(prepare-description(none) == none)
#assert(
prepare-description(auto, plain-body: [Hello]) == "Hello",
)
```

--------------------------------

### Configure book discord

Source: https://myriad-dreamin.github.io/shiroa/format/book-meta.html

Sets the Discord server invite link for the book.

```typst
#book-meta(
  discord: "https://discord.gg/Myriad-Dreamin",
)
```

--------------------------------

### get-book-meta: Query final book metadata with mapper

Source: https://myriad-dreamin.github.io/shiroa/supports/metadata.html

Use get-book-meta to read the final book metadata during page, theme, or ebook compilation. The mapper receives none when no metadata is available, a dictionary for a normal book, or an array if multiple matching metadata values exist. This example defines a site-title function that extracts the raw title or title field.

```typst
#import "@preview/shiroa:0.4.0": get-book-meta
#let site-title() = get-book-meta(mapper: meta => {
  if type(meta) == array {
    meta = meta.first()
  }
  if meta == none {
    ""
  } else if "raw-title" in meta {
    if meta.raw-title == none { "" } else { meta.raw-title }
  } else if "title" in meta and type(meta.title) == str {
    meta.title
  } else if "title" in meta {
    meta.title.content
  } else {
    ""
  }
})
#context site-title()
```

--------------------------------

### Configure repository metadata

Source: https://myriad-dreamin.github.io/shiroa/paged/theme/builtin.html

Sets up repository links for the book header.

```typst
#import "@preview/shiroa:0.4.0": book-meta  
  
#book-meta(  
repository: "https://github.com/example/my-book",  
repository-edit: "https://github.com/example/my-book/edit/main/docs/{path}",  
summary: [],  
)
```

--------------------------------

### plain-text: extract plain text from Typst content

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/content.html

Use plain-text to extract a plain-text representation from Typst content. Images contribute their alternative text; line and paragraph breaks are preserved; formatting is removed. The limit parameter counts Unicode grapheme clusters rather than bytes. The example imports the function and trims the result after applying a limit of 160.

```typst
#import "@preview/shiroa:0.4.0": plain-text

#let description = plain-text([
A *formatted* introduction with $x^2$.
], limit: 160).trim()
```

--------------------------------

### Shiroa project template with Starlight and mdBook themes

Source: https://myriad-dreamin.github.io/shiroa/theme/builtin.html

Minimal selection pattern for an initialized book. It sets page dimensions for PDF/web targets and uses the appropriate theme wrapper (Starlight for HTML, mdBook for PDF/web) while passing `plain-body: body` to both themes. Keep `plain-body: body` even when another show rule styles the visible chapter, as it gives both themes a stable source for automatic metadata.

```typst
#import "@preview/shiroa:0.4.0": (
  get-page-width,
  is-html-target,
  is-pdf-target,
  is-web-target,
)
#let project(
  title: "",
  description: auto,
  body,
) = {
  set page(
    width: get-page-width(),
    height: auto,
  ) if is-pdf-target() or is-web-target()
  show: if is-html-target(exclude-wrapper: true) {
    import "@preview/shiroa-starlight:0.4.0": starlight
    starlight.with(
      include "book.typ",
      title: title,
      description: description,
      plain-body: body,
    )
  } else {
    import "@preview/shiroa-mdbook:0.4.0": mdbook
    mdbook.with(
      include "book.typ",
      title: title,
      description: description,
      plain-body: body,
    )
  }
  body
}

```

```typst
#import "@preview/shiroa:0.4.0": (
  get-page-width,
  is-html-target,
  is-pdf-target,
  is-web-target,
)
#let project(
  title: "",
  description: auto,
  body,
) = {
  set page(
    width: get-page-width(),
    height: auto,
  ) if is-pdf-target() or is-web-target()
  show: if is-html-target(exclude-wrapper: true) {
    import "@preview/shiroa-starlight:0.4.0": starlight
    starlight.with(
      include "book.typ",
      title: title,
      description: description,
      plain-body: body,
    )
  } else {
    import "@preview/shiroa-mdbook:0.4.0": mdbook
    mdbook.with(
      include "book.typ",
      title: title,
      description: description,
      plain-body: body,
    )
  }
  body
}

```

--------------------------------

### Import and assert book-sys

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/targets.html

Import book-sys and assert it contains the keys target, page-width, and sys-is-html-target. Use this dictionary when passing all target state through another API; prefer the individual functions in new templates.

```typst
#import "@preview/shiroa:0.4.0": book-sys

#assert("target" in book-sys)
#assert("page-width" in book-sys)
#assert("sys-is-html-target" in book-sys)
```

--------------------------------

### Configure build-meta

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/book-description.html

Sets the build destination directory, which can be overridden by the CLI.

```typst
#import "@preview/shiroa:0.4.0": build-meta

#build-meta(dest-dir: "dist")
```

--------------------------------

### Configure book repository

Source: https://myriad-dreamin.github.io/shiroa/format/book-meta.html

Sets the GitHub repository URL for the book.

```typst
#book-meta(
  repository: "https://github.com/Myriad-Dreamin/shiroa",
)
```

--------------------------------

### Apply the custom theme

Source: https://myriad-dreamin.github.io/shiroa/format/theme.html

Applies the custom theme using a show rule within the project configuration.

```Typst
_// Compile this example with Typst's HTML target._
#import "my-theme.typ": my-theme
#let project(
  title: "",
  description: auto,
  body,
) = {
  show: my-theme.with(
    include "book.typ",
    title: title,
    description: description,
    plain-body: body,
  )
  body
}
```

--------------------------------

### Build a minimal native HTML theme

Source: https://myriad-dreamin.github.io/shiroa/format/theme.html

Creates a custom HTML theme using html.elem that handles metadata, viewport settings, and content structure for HTML targets.

```Typst
_// Compile this example with Typst's HTML target._
#import "@preview/shiroa:0.4.0": (
  is-html-target,
  plain-text,
  prepare-description,
)
#let my-theme(
  book,
  body,
  title: "",
  description: none,
  plain-body: auto,
) = {
  if not is-html-target() {
    return body
  }
  let plain-body = if plain-body == auto { body } else { plain-body }
  let description = prepare-description(
    description,
    plain-body: plain-body,
  )
  html.elem(
    "html",
    {
      html.elem("head", {
        html.elem("meta", attrs: (charset: "utf-8"))
        html.elem(
          "meta",
          attrs: (
            name: "viewport",
            content: "width=device-width, initial-scale=1.0",
          ),
        )
        html.elem("title", plain-text(title))
        if description != none {
          html.elem(
            "meta",
            attrs: (name: "description", content: description),
          )
        }
      })
      html.elem("body", {
        book
        html.elem("main", {
          html.elem("h1", title)
          body
        })
      })
    },
    attrs: (lang: "en"),
  )
}
```

--------------------------------

### Importing all package members for book.typ

Source: https://myriad-dreamin.github.io/shiroa/paged/supports/package.html

Importing all members is convenient for book.typ files to access all book-description helpers.

```typst
#import "@preview/shiroa:0.4.0": *  
  
#show: book  
  
#book-meta(  
title: "My Book",  
summary: [  
#prefix-chapter("introduction.typ")[Introduction]  
= Guide  
- #chapter("guide/start.typ")[Getting Started]  
],  
)
```
Tokens:
Raw