shiroa

CLI Build Command

The build command is used to render your book:

shiroa build
shiroa build

It will parse the book metadata, render each chapter, and write the generated site to the output directory.

Specify a directory

The buildbuild command can take a directory as an argument to use as the book’s root instead of the current working directory.

shiroa build path/to/book
shiroa build path/to/book

--root

The --root--root option specifies the root directory for typst source files. It is interpreted relative to current work directory of shiroashiroa process.

For example. When a book is created with the main file book-project1/book.typbook-project1/book.typ, and you want to access a template file with path common/book-template.typcommon/book-template.typ, please build it with following command:

shiroa build --root . book-project1
shiroa build --root . book-project1

Then you can access the template with the absolute path in typst:

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

The older -w-w/--workspace--workspace option is deprecated. Use --root--root instead.

--meta-source

The --meta-source--meta-source option controls how shiroa discovers book metadata.

  • strictstrict (default): query shiroa metadata from book.typbook.typ, including <shiroa-book-meta><shiroa-book-meta> and <shiroa-build-meta><shiroa-build-meta>.
  • outlineoutline: infer chapters from the outline of a Typst entry file. If the entry also contains shiroa metadata, the explicit metadata is used first.
shiroa build --meta-source outline article.typ
shiroa build --meta-source outline article.typ

--font-path

The --font-path--font-path option adds additional directories that are recursively searched for fonts for typst source files. If multiple paths are specified, they are separated by the system’s path separator (:: on Unix-like systems and ;; on Windows).

It can also be set with the TYPST_FONT_PATHSTYPST_FONT_PATHS environment variable.

shiroa build --font-path ./fonts
shiroa build --font-path ./fonts

--input

The --input--input option adds a string key-value pair visible through sys.inputssys.inputs, matching typst compile --inputtypst compile --input.

shiroa build --input edition=web
shiroa build --input edition=web

--package-path

The --package-path--package-path option specifies a custom path to local Typst packages. It can also be set with the TYPST_PACKAGE_PATHTYPST_PACKAGE_PATH environment variable.

--package-cache-path

The --package-cache-path--package-cache-path option specifies a custom path to the Typst package cache. It can also be set with the TYPST_PACKAGE_CACHE_PATHTYPST_PACKAGE_CACHE_PATH environment variable.

--dest-dir, -d

The --dest-dir--dest-dir (-d-d) option allows you to change the output directory for the book. Relative paths are interpreted relative to the book’s root directory. If not specified it will default to the value of #build-meta(dest-dir: ...)#build-meta(dest-dir: ...) in book.typbook.typ, or to ./dist./dist.

shiroa build --dest-dir ../dist
shiroa build --dest-dir ../dist

--path-to-root

When your website’s root is not exact serving the book, use --path-to-root--path-to-root to specify the path to the root of the book site. For example, if you own myriad-dreamin.github.iomyriad-dreamin.github.io and have mounted the book to /shiroa//shiroa/, you can access https://myriad-dreamin.github.io/shiroa/cli/main.htmlhttps://myriad-dreamin.github.io/shiroa/cli/main.html to get the generated content of cli/main.typcli/main.typ.

shiroa build --path-to-root /shiroa/ book-project1
shiroa build --path-to-root /shiroa/ book-project1

--mode

The --mode--mode option allows you to specify the mode of rendering typst document. The default mode is dyn-pageddyn-paged.

  • (Default) dyn-pageddyn-paged: dynamically render as paged document.
  • (Experimental) static-htmlstatic-html: statically render the whole document, the embedded frames are not resizable.
  • (Todo) static-html-dyn-pagedstatic-html-dyn-paged: statically render html parts as much as possible, and leave frames rendered dynamically.

The dynamically rendering means that some elements will be rendered by a wasm renderer in the browser.

--allowed-url-source

The --allowed-url-source--allowed-url-source option configures the regular expression used to allow external URL sources for command-backed HTML embeds. The default allows player.bilibili.complayer.bilibili.com.

shiroa build --allowed-url-source '^(player\.bilibili\.com|www\.youtube\.com)$'
shiroa build --allowed-url-source '^(player\.bilibili\.com|www\.youtube\.com)$'