Typst Support - Book Description

The root book.typbook.typ describes the project, chapter order, hierarchy, source paths, and build destination. These functions are normally used there. See book.typ, Book Metadata, and Build Metadata for the complete file format.

book(content)book(content) is a show rule for the root book.typbook.typ. It preserves the book description and emits Shiroa’s package metadata.

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

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

book-meta(...)book-meta(...) stores project metadata in <shiroa-book-meta><shiroa-book-meta> and makes it available to the CLI and themes.

• titletitle (strstr or content): Site or book title.
• descriptiondescription (strstr): Default description of the book.
• repositoryrepository (strstr): Repository URL shown by themes.
• repository-editrepository-edit (strstr): Edit URL template. Themes replace {path}{path} with the current source path.
• discorddiscord (strstr): Discord invitation used by themes that render social links.
• authorsauthors (arrayarray): An array of author names. Passing a string is an error.
• languagelanguage (strstr): Main language, for example "en""en" or "zh""zh".
• summarysummary (content): Parts, chapters, dividers, and nested chapters.

#import "@preview/shiroa:0.4.0": build-meta
#build-meta(dest-dir: "dist")

#import "@preview/shiroa:0.4.0": build-meta
#build-meta(dest-dir: "dist")

Stores build metadata in <shiroa-build-meta><shiroa-build-meta>. dest-dirdest-dir is resolved relative to the book root and can be overridden by the CLI’s --dest-dir--dest-dir option.

chapter(link, title, section: auto)chapter(link, title, section: auto) creates a chapter entry for book-meta.summarybook-meta.summary.

• linklink (strstr or nonenone): Source path relative to book.typbook.typ. nonenone creates a draft chapter.
• titletitle (content): Text displayed by the sidebar.
• sectionsection (autoauto, nonenone, strstr, or array<int>array<int>): autoauto numbers the chapter from its position; nonenone makes it unnumbered; a string such as "2.3""2.3" or an integer array sets the number explicitly.

#import "@preview/shiroa:0.4.0": book-meta, chapter
#book-meta(
  summary: [
    = Guide
    - #chapter("guide/start.typ")[Getting Started]
      - #chapter("guide/config.typ", section: "1.1")[Configuration]
    - #chapter(none)[Planned chapter]
  ],
)

#import "@preview/shiroa:0.4.0": book-meta, chapter
#book-meta(
  summary: [
    = Guide
    - #chapter("guide/start.typ")[Getting Started]
      - #chapter("guide/config.typ", section: "1.1")[Configuration]
    - #chapter(none)[Planned chapter]
  ],
)

prefix-chapter(link, title)prefix-chapter(link, title) and suffix-chapter(link, title)suffix-chapter(link, title) create unnumbered chapters before or after the main chapter list.

#import "@preview/shiroa:0.4.0": (
  book-meta,
  chapter,
  prefix-chapter,
  suffix-chapter,
)
#book-meta(
  summary: [
    #prefix-chapter("preface.typ")[Preface]
    - #chapter("chapter.typ")[Chapter]
    #suffix-chapter("appendix.typ")[Appendix]
  ],
)

#import "@preview/shiroa:0.4.0": (
  book-meta,
  chapter,
  prefix-chapter,
  suffix-chapter,
)
#book-meta(
  summary: [
    #prefix-chapter("preface.typ")[Preface]
    - #chapter("chapter.typ")[Chapter]
    #suffix-chapter("appendix.typ")[Appendix]
  ],
)

#import "@preview/shiroa:0.4.0": book-meta, chapter, divider
#book-meta(
  summary: [
    - #chapter("guide.typ")[Guide]
    #divider
    - #chapter("reference.typ")[Reference]
  ],
)

#import "@preview/shiroa:0.4.0": book-meta, chapter, divider
#book-meta(
  summary: [
    - #chapter("guide.typ")[Guide]
    #divider
    - #chapter("reference.typ")[Reference]
  ],
)

Adds a visual divider to a summary. Whether and how it is displayed is decided by the active theme.

partbreak()partbreak() ends the current part without starting another named part. The chapters that follow are rendered as a root-level group.

#import "@preview/shiroa:0.4.0": book-meta, chapter, partbreak
#book-meta(
  summary: [
    = Tutorials
    - #chapter("tutorial.typ")[Tutorial]
    #partbreak()
    - #chapter("reference.typ")[Reference]
  ],
)

#import "@preview/shiroa:0.4.0": book-meta, chapter, partbreak
#book-meta(
  summary: [
    = Tutorials
    - #chapter("tutorial.typ")[Tutorial]
    #partbreak()
    - #chapter("reference.typ")[Reference]
  ],
)

external-book(spec: none)external-book(spec: none) loads another book description without displaying it. visit-summary(x, visit)visit-summary(x, visit) walks a converted summary using callbacks named incinc, chapterchapter, and partpart. The bundled ebook template uses both helpers to combine all chapters into a single paged document. Their callback protocol is an advanced API and may evolve with the summary representation.