Metadata-Version: 2.3
Name: zensical2pdf
Version: 0.1.0
Summary: Render a Zensical documentation site to PDF via md2typst and Typst
Author: Stefane Fermigier
Author-email: Stefane Fermigier <sf@abilian.com>
Requires-Dist: md2typst>=0.3.6
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# zensical2pdf

Render a [Zensical](https://zensical.org/) documentation site to a single, book-like PDF.

It converts each page to [Typst](https://typst.app/) with [md2typst](https://pypi.org/project/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.
