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
typstcommand on yourPATH(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 containingzensical.toml(default: current directory).-o: where to write the PDF (default:<site_name>.pdfin 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.tabsinproject.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(orREADME.md) uses that page as the section's title and introduction, likenavigation.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 itsindex.mdfirst, 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.
Metadata
Release files for zensical2pdf 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zensical2pdf-0.1.0.tar.gz | 9.4 kB | Without provenance | Details for zensical2pdf-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zensical2pdf-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for zensical2pdf-0.1.0-py3-none-any.whl |
Total release size: 20.9 kB
Release files / zensical2pdf-0.1.0.tar.gz
| Download URL | zensical2pdf-0.1.0.tar.gz |
|---|---|
| Size | 9.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fc2afdae711a39eaf52bb57036e4353a81252ccad714c46d3500a8e1e659db0f
|
|
BLAKE2b-256 checksum How to use checksums |
eb58f3066bd1cce6f6fe107e35abc0ca5e848b0fae9bbf4403ee27b67ba374eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.12 {"installer":{"name":"uv","version":"0.12.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / zensical2pdf-0.1.0-py3-none-any.whl
| Download URL | zensical2pdf-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2771f847006abb873f283799a5067f32e67300580437d71ae95bdd5c65d552c
|
|
BLAKE2b-256 checksum How to use checksums |
0718496a3c5f9e35ab7c08fef15536b0e25c73bd08051ecf6d607c961c821d18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.12 {"installer":{"name":"uv","version":"0.12.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for zensical2pdf 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.