1. Introduction
  3. User Guide
  4. 1. Installation
  5. 2. Get Started
  6. 3. Frequently Asked Questions
  7. 4. Further reading
  9. Reference Guide
  10. 5. Command Line Tool
    1. 5.1. init
    2. 5.2. build
    3. 5.3. serve
    4. 5.4. clean
    5. 5.5. completions
  12. 6. Format
    1. 6.1. book.typ
      1. 6.1.1. Book Metadata
        1. 6.1.1.1. Draft chapter
      3. 6.1.2. Build Metadata
    3. 6.2. Theme
    4. 6.3. Typst Support
      1. 6.3.1. Cross Reference
        1. 6.3.1.1. Cross Reference Sample
      3. 6.3.2. Embed Sanitized HTML Elements
        1. 6.3.2.1. Multimedia components
      5. 6.3.3. Semantic Page Description
  14. 7. For developers
    1. 7.1. Typst-side APIs
    2. 7.2. shiroa CLI Internals
    3. 7.3. Alternative Backends

shiroa

#

The build command

The build command is used to render your book:

1
shiroa build
1
shiroa build

It will try to parse your book.typ file to understand the structure and metadata of your book and fetch the corresponding files. Note that files mentioned in book.typ but not present will be created.

The rendered output will maintain the same directory structure as the source for convenience. Large books will therefore remain structured when rendered.

#

Specify a directory

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

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

#

–workspace, -w

Note: The workspace is a typst-specific command.

The --workspace option specifies the root directory of typst source files, which is like the --root option of typst-cli. It is interpreted relative to current work directory of shiroa process.

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

1
shiroa build -w . book-project1
1
shiroa build -w . book-project1

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

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

#

–dest-dir, -d

The --dest-dir (-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 the build.build-dir key in book.toml, or to ./book.

#

–path-to-root

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

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

#

–mode

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

  • (Default) dynamic-paged: dynamically render as paged document.
  • (Experimental) static-html: statically render the whole document, the embedded frames are not resizable.
  • (Todo) static-html-static-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.

#

–theme

Specify a theme directory to copy recursively. This allows you to use custom themes.

The files will be copied to the theme/ in the output directory.

The default theme is located at themes/mdbook. You can start by copying this theme and modifying it to your needs.

Currently, no interface is designed for custom themes, i.e. everything is working occasionally. If you have any questions, design or feature requests about theming, please open an issue in the repository.