`pdk pdf`¶

pdk pdf builds one PDF from the completed Zensical website and the PDF settings in the project configuration.

Use the PDF generation task guide to prepare renderers, configure the document, and resolve build failures.

Synopsis¶

Use the complete-document form or select one Markdown page for focused review.

pdk pdf [--config-file PATH] [--markdown-file PAGE]
pdk pdf --prepare COMPONENT [--prepare COMPONENT ...]

Working directory¶

Run this command from the project root, after building the website there. Use --config-file PATH when deliberately building another configuration; --markdown-file remains relative to that configuration's docs_dir.

From the wrong directory it normally reports project configuration not found: .../zensical.toml. If the configuration is found but the website has not been built, expect built site not found: ...; run zensical build first instead.

Options¶

Table 42.1 lists the PDF source-selection controls.

1. PDF build options

Option	Behaviour
`-f`, `--config-file PATH`	Read another Zensical configuration; defaults to `zensical.toml`.
`-m`, `--markdown-file PAGE`	Build only one Markdown page relative to `docs_dir`, ignoring `nav` for the PDF contents.
`--prepare COMPONENT`	Validate and prepare one project-local PDF component without requiring a built site or producing a PDF; repeat it or use `all` for every component supported on the current platform.
`-h`, `--help`	Show installed help and exit.

Inputs and output¶

The command uses the completed site_dir; build the website first with zensical build --clean --strict. It assembles the pages in configured navigation order, processes PDF-only features, then asks Pandoc and WeasyPrint to write the configured PDF path.

The single-page option still reads layout, fonts, styles, and renderer settings from the configuration. It changes only the scope of the PDF contents.

PDF runtime policy¶

Optional runtime policy lives in pdk-pdf.toml beside the selected Zensical configuration. A missing file uses supported defaults and an ordinary build does not create one. The minimal file is:

schema_version = 1

Renderer overrides may select latest, supported, or an exact version and may set preload = true. Runtime overrides may select a version. G1 accepts only location = "cache": it means the derived project-local store at .prodockit/cache/pdf/, never an absolute path committed to the repository. Resolved versions, hashes, platform identity and last-known-good state are recorded inside that store rather than in pdk-pdf.toml.

PDF-only Python packages have a separate project policy file, pdf-requirements.txt, created by pdk pdf when missing. On macOS and Linux its standard WeasyPrint requirement is installed into the active project environment on first use. If the index is enabled, PyMuPDF is added for that build. The preparation fingerprint includes the file, interpreter and environment, so another virtual environment prepares its own packages while an unchanged warm build performs no installation.

The preparation interface is intentionally provider-gated. Pandoc 3.10.1 is available on supported macOS, Linux, Windows x64 and Windows ARM64 targets; Windows ARM64 runs the reviewed Windows x64 executable through Windows 11 app emulation for citation-enabled website builds. The Inter 4.1/JetBrains Mono 2.304 font bundle is available on supported macOS, Linux and Windows x64 targets; Windows x64 also provides WeasyPrint 70. Local PDF generation remains unsupported on Windows ARM64. A healthy cache is a fast local validation with no provider or network call.

Exit status¶

A missing or mismatched environment, incomplete built site, invalid PDF configuration, renderer failure, or unwritable output produces a non-zero exit and preserves the underlying tool's useful error detail.

Use these commands to validate inputs or build the companion source artifact:

pdk config checks PDF settings and inputs without building.
pdk source-bundle renders the underlying source as a separate submission artifact.

pdk pdf¶