zensical2pdf

Render a Zensical documentation site to a single, book-like PDF.

It converts each page to Typst with md2typst, assembles the pages in the order of the nav in zensical.toml, applies a Typst template and compiles the result with the typst binary.

Requirements

• Python 3.12+
• The typst command on your PATH (brew install typst, cargo install typst-cli, or a release from https://github.com/typst/typst/releases).

Usage

uv tool install zensical2pdf   # or: pip install zensical2pdf
cd my-docs                     # the directory holding zensical.toml
zensical2pdf                   # writes <site_name>.pdf

Options:

zensical2pdf [SITE_DIR] [-o OUTPUT.pdf] [--template FILE.typ] [--build-dir DIR] [--dump-template]

• SITE_DIR: directory containing zensical.toml (default: current directory).
• -o: where to write the PDF (default: <site_name>.pdf in the current directory).
• --template: a custom Typst stylesheet (see below).
• --build-dir: keep the generated Typst sources in this directory for debugging or hand-tuning.
• --dump-template: print the default stylesheet to standard output.

How the site becomes a book

• With navigation.tabs in project.theme.features, each top-level section of the nav becomes a part and the entries below it become chapters. Without tabs, top-level entries are chapters.
• A section whose first entry is an index.md (or README.md) uses that page as the section's title and introduction, like navigation.indexes.
• Pages without a level-1 heading get one from their nav title, front-matter title, or file name.
• Without a nav, each folder contributes its index.md first, then its remaining files and subfolders in alphabetical order.
• Links between pages of the site become internal PDF links. External links are kept as URLs.
• Admonitions (!!! note), collapsible details (??? tip) and content tabs (=== "Tab") render as colored call-out boxes.
• Remote images are replaced by their alt text; local images are scaled down to the text width when needed.

Customizing the look

zensical2pdf --dump-template > my-template.typ
# edit fonts, colors, page size, admonition styles...
zensical2pdf --template my-template.typ

A template must export book (the show rule applied to the whole document, receiving title, subtitle, author, copyright, lang and parts), admonition(kind, title, body) and fit-image(..args). Fonts and colors are defined at the top of the default template.

Limitations

• Zensical/Material extensions with no print equivalent are ignored or stripped: icon shortcodes, attribute lists, grid cards, snippets, mkdocstrings directives.
• Same-page anchors (#section) are left as written and do not jump anywhere in the PDF.