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

#

Book Metadata

#

title string

Specify the title of the book.

1
#book-meta(
2
  title: "../dist",
3
)
1
#book-meta(
2
  title: "../dist",
3
)

#

authors array<string>

Specify the author(s) of the book.

1
#book-meta(
2
  authors: ("Alice", "Bob"),
3
)
1
#book-meta(
2
  authors: ("Alice", "Bob"),
3
)

#

summary (required) content

Its formatting is very strict and must follow the structure outlined below to allow for easy parsing. Any element not specified below, be it formatting or textual, is likely to be ignored at best, or may cause an error when attempting to build the book.

1
#book-meta(
2
  summary: [
3
    #prefix-chapter("pre.typ")[Prefix Chapter]
4
    = User Guide
5
    - #chapter("1.typ", section: "1")[First Chapter]
6
        - #chapter("1.1.typ", section: "1.1")[First sub]
7
    - #chapter("2.typ", section: "1")[Second Chapter]
8
    #suffix-chapter("suf.typ")[Suffix Chapter]
9
  ],
10
)
1
#book-meta(
2
  summary: [
3
    #prefix-chapter("pre.typ")[Prefix Chapter]
4
    = User Guide
5
    - #chapter("1.typ", section: "1")[First Chapter]
6
        - #chapter("1.1.typ", section: "1.1")[First sub]
7
    - #chapter("2.typ", section: "1")[Second Chapter]
8
    #suffix-chapter("suf.typ")[Suffix Chapter]
9
  ],
10
)

  1. Prefix Chapter - Before the main numbered chapters, prefix chapters can be added that will not be numbered. This is useful for forewords, introductions, etc. There are, however, some constraints. Prefix chapters cannot be nested; they should all be on the root level. And you cannot add prefix chapters once you have added numbered chapters.

    1
    #prefix-chapter("pre.typ")[Prefix Chapter]
    2
    - #chapter("1.typ", section: "1")[First Chapter]
    1
    #prefix-chapter("pre.typ")[Prefix Chapter]
    2
    - #chapter("1.typ", section: "1")[First Chapter]

  2. Part Title - Headers can be used as a title for the following numbered chapters. This can be used to logically separate different sections of the book. The title is rendered as unclickable text. Titles are optional, and the numbered chapters can be broken into as many parts as desired.

    1
    = My Part Title
    2

    3
    - #chapter("1.typ", section: "1")[First Chapter]
    1
    = My Part Title
    2

    3
    - #chapter("1.typ", section: "1")[First Chapter]

  3. Numbered Chapter - Numbered chapters outline the main content of the book and can be nested, resulting in a nice hierarchy (chapters, sub-chapters, etc.).

    1
    = Title of Part
    2

    3
    - #chapter("first.typ", section: "1")[First Chapter]
    4
      - #chapter("first-sub-chapter.typ", section: "1.1")[First sub-chapter]
    5
    - #chapter("second.typ", section: "1")[Second Chapter]
    6

    7
    = Title of Another Part
    8

    9
    - #chapter("another/chapter.typ", section: "1")[Another Chapter]
    1
    = Title of Part
    2

    3
    - #chapter("first.typ", section: "1")[First Chapter]
    4
      - #chapter("first-sub-chapter.typ", section: "1.1")[First sub-chapter]
    5
    - #chapter("second.typ", section: "1")[Second Chapter]
    6

    7
    = Title of Another Part
    8

    9
    - #chapter("another/chapter.typ", section: "1")[Another Chapter]

    Numbered chapters can be denoted either -.

  4. Suffix Chapter - Like prefix chapters, suffix chapters are unnumbered, but they come after numbered chapters.

    1
    = Last Part
    2

    3
    - #chapter("second.typ", section: "10")[Last Chapter]
    4

    5
    #suffix-chapter("suf.typ")[Title of Suffix Chapter]
    1
    = Last Part
    2

    3
    - #chapter("second.typ", section: "10")[Last Chapter]
    4

    5
    #suffix-chapter("suf.typ")[Title of Suffix Chapter]

  5. Draft chapters - Draft chapters are chapters without a file and thus content. The purpose of a draft chapter is to signal future chapters still to be written. Or when still laying out the structure of the book to avoid creating the files while you are still changing the structure of the book a lot. Draft chapters will be rendered in the HTML renderer as disabled links in the table of contents, as you can see for the next chapter in the table of contents on the left. Draft chapters are written like normal chapters but without writing the path to the file.

    1
    #chapter(none, section: "5.2")[Draft Chapter]
    1
    #chapter(none, section: "5.2")[Draft Chapter]

  6. Separators - Separators can be added before, in between, and after any other element. They result in an HTML rendered line in the built table of contents. A separator is a line containing exclusively dashes and at least three of them: ---.

    1
    = My Part Title
    2

    3
    #prefix-chapter("pre.typ")[A Prefix Chapter]
    4

    5
    #divider()
    6

    7
    - #chapter("1.typ", section: "1")[First Chapter]
    1
    = My Part Title
    2

    3
    #prefix-chapter("pre.typ")[A Prefix Chapter]
    4

    5
    #divider()
    6

    7
    - #chapter("1.typ", section: "1")[First Chapter]

#

Example

Below is the summary content for the book.typ for this guide, with the resulting table of contents as rendered to the left.

1
#prefix-chapter("introduction.typ")[Introduction]
2
= User Guide
3
- #chapter("guide/installation.typ")[Installation]
4
- #chapter("guide/get-started.typ")[Get Started]
5
- #chapter("guide/faq.typ")[Frequently Asked Questions]
6
- #chapter(none)[Further reading]
7
= Reference Guide
8
- #chapter("cli/main.typ")[Command Line Tool]
9
  - #chapter("cli/init.typ")[init]
10
  - #chapter("cli/build.typ")[build]
11
  - #chapter("cli/serve.typ")[serve]
12
  - #chapter("cli/clean.typ")[clean]
13
  - #chapter("cli/completions.typ")[completions]
14
- #chapter("format/main.typ")[Format]
15
  - #chapter("format/book.typ")[book.typ]
16
    - #chapter("format/book-meta.typ")[Book Metadata]
17
      - #chapter(none)[Draft chapter]
18
    - #chapter("format/build-meta.typ")[Build Metadata]
19
  - #chapter("format/theme.typ")[Theme]
20
  - #chapter("format/supports.typ")[Typst Support]
21
    - #chapter("format/supports/cross-ref.typ")[Cross Reference]
22
      - #chapter("format/supports/cross-ref-sample.typ")[Cross Reference Sample]
23
    - #chapter("format/supports/embed-html.typ")[Embed Sanitized HTML Elements]
24
      - #chapter("format/supports/multimedia.typ")[Multimedia components]
25
    - #chapter("format/supports/sema-desc.typ")[Semantic Page Description]
26
- #chapter(none)[For developers]
27
  - #chapter(none)[Typst-side APIs]
28
  - #chapter(none)[shiroa CLI Internals]
1
#prefix-chapter("introduction.typ")[Introduction]
2
= User Guide
3
- #chapter("guide/installation.typ")[Installation]
4
- #chapter("guide/get-started.typ")[Get Started]
5
- #chapter("guide/faq.typ")[Frequently Asked Questions]
6
- #chapter(none)[Further reading]
7
= Reference Guide
8
- #chapter("cli/main.typ")[Command Line Tool]
9
  - #chapter("cli/init.typ")[init]
10
  - #chapter("cli/build.typ")[build]
11
  - #chapter("cli/serve.typ")[serve]
12
  - #chapter("cli/clean.typ")[clean]
13
  - #chapter("cli/completions.typ")[completions]
14
- #chapter("format/main.typ")[Format]
15
  - #chapter("format/book.typ")[book.typ]
16
    - #chapter("format/book-meta.typ")[Book Metadata]
17
      - #chapter(none)[Draft chapter]
18
    - #chapter("format/build-meta.typ")[Build Metadata]
19
  - #chapter("format/theme.typ")[Theme]
20
  - #chapter("format/supports.typ")[Typst Support]
21
    - #chapter("format/supports/cross-ref.typ")[Cross Reference]
22
      - #chapter("format/supports/cross-ref-sample.typ")[Cross Reference Sample]
23
    - #chapter("format/supports/embed-html.typ")[Embed Sanitized HTML Elements]
24
      - #chapter("format/supports/multimedia.typ")[Multimedia components]
25
    - #chapter("format/supports/sema-desc.typ")[Semantic Page Description]
26
- #chapter(none)[For developers]
27
  - #chapter(none)[Typst-side APIs]
28
  - #chapter(none)[shiroa CLI Internals]

#

description string

A description for the book, which is added as meta information in the html <head> of each page.

1
#book-meta(
2
  description: "shiroa Documentation",
3
)
1
#book-meta(
2
  description: "shiroa Documentation",
3
)

#

repository string

The github repository for the book.

1
#book-meta(
2
  repository: "https://github.com/Myriad-Dreamin/shiroa",
3
)
1
#book-meta(
2
  repository: "https://github.com/Myriad-Dreamin/shiroa",
3
)

#

language string

The main language of the book, which is used as a html language attribute <html lang="en"> for example.

1
#book-meta(
2
  language: "en",
3
)
1
#book-meta(
2
  language: "en",
3
)