Build and publish¶

The website and PDF come from the same Markdown and zensical.toml, but they are separate outputs. Build both, inspect both, and run the checks before publishing a significant change.

Prepare the terminal¶

Run all commands from the repository directory with its virtual environment active.

Change to the repository directory

Replace the example path with the folder containing your project:
```
cd path/to/your-project
```
Activate the project environment
macOS Windows Linux (Ubuntu)
source .venv/bin/activate
.\.venv\Scripts\Activate.ps1
source .venv/bin/activate
The prompt normally gains (.venv) when activation succeeds.

Build both outputs¶

The website and PDF process builds the website first, then uses that completed output to build the PDF:

zensical build --clean --strict
prodockit pdf

The outputs are:

docs/site_documentation.pdf — the finished PDF.
public/ — the complete website ready to publish.

--clean prevents files removed from the source remaining in the website. --strict turns Zensical warnings into failures so they cannot pass unnoticed in the publishing pipeline. prodockit pdf does not run Zensical. It reads the generated pages and atomically adds the finished PDF to public/, so the website's Download PDF link works without a second website build.

The PDF guide documents every PDF setting, output file, and known limitation. The Zensical build guide covers the website command in detail.

Diagrams and maths¶

Diagram and maths rendering needs no npm packages or browser for the PDF. Prodockit downloads and verifies project-local Mermaid and MathJax runtimes on first use. PDF maths needs Node.js on PATH to run MathJax's SVG adapter; the website uses Zensical's MathJax configuration and a browser CDN.

To prepare all PDF components ahead of the first build, run:

pdk pdf --prepare all

A document with no maths does not need Node.js for PDF rendering. Ordinary pdk pdf prepares only the components it uses.

Inspect the output, not only the exit code

Missing renderers can leave Mermaid definitions or TeX source visible in the finished document. Open the affected pages in both outputs after the build. The automated checks also look for common forms of unrendered source.

Use Additional tooling for installation and the prodockit PDF guide for renderer configuration and troubleshooting.

Fonts¶

The website can load configured Fonts when a reader opens it. A PDF builder must find the actual desktop font files on the machine doing the build. If they are absent, WeasyPrint may substitute another font without failing.

The template uses Inter for body text and JetBrains Mono for code. Install the .ttf or .otf desktop versions, not .woff web-font files. The Getting started section covers the operating-system steps.

After changing a font:

Build the PDF again.
Inspect headings, body text, code, symbols, and page breaks.
Compare a representative page with the earlier PDF.
Confirm the publishing pipeline installs the same fonts.

The PDF typography reference contains the font-detection and embedding details.

Keep the project up to date¶

The Maintenance workflow covers two different kinds of update:

A template update brings shared workflows, styles, and configuration changes into a project originally made from prodockit-template.
A dependency update changes versions of prodockit, Zensical, WeasyPrint, Pandoc, or another build input.

Review either kind of update before combining it with your writing.

Update from prodockit-template¶

Update from prodockit-template by previewing the update without changing the project:

prodockit template-sync

If the preview is appropriate, apply it on the branch prepared by the command:

prodockit template-sync --apply

Before changing a template file, the command checks the selected template's paired Prodockit release and the complete supported toolchain. If the active environment needs a different Prodockit version, it shows the exact install, upgrade, or downgrade and asks for confirmation. It then continues under that version in a fresh process, previews the work needed by Adopt, and asks separately before applying it. Both questions default to No. A newer Prodockit is not automatically preferred over the release paired with the selected template.

.prodockit-components.toml belongs to the project: Template Sync does not copy it from the template or overwrite it. Its Adopt prerequisite uses saved choices when the file exists. For an older project without the file, it uses the same Mermaid and mathematics selections inferred from the existing Zensical configuration as prodockit adopt and prodockit diag, then saves the local record only after the separate Component choices stage is approved. That manifest-only stage does not mean the project's extensions or styles need changing.

If either confirmation is declined, or installation, handoff, Adopt, or verification fails, the template files, applied-release stamp, and update branch remain unchanged. Correct the reported problem and rerun the same command; completed prerequisites are reassessed and skipped. For an explicitly unattended update, opt in to both environment changes:

prodockit template-sync --apply --accept-prodockit --accept-adopt

The manifest distinguishes template-owned files from your content. The merge preserves every existing project-owned file and the PDF policy in pdk-pdf.toml. It can add a new setting, but it does not reset your page size, margins, duplex choice, or other existing PDF configuration.

Review the staged changes and rebuild both outputs before committing. The template-sync guide explains preserved files, conflicts, --force, verbose output, and direct updates to main.

Validate the project configuration¶

Check the settings Prodockit will actually use before starting a build:

prodockit config --check

The command resolves zensical.toml, validates Prodockit-owned settings, and checks that referenced navigation pages, images, citation styles, optional renderers, and enabled extensions are available. It does not build the site, change the configuration, or inspect unrelated Zensical settings. A failure names the missing or invalid input so it can be corrected before a longer website or PDF build.

Run it after changing configuration or adding an optional renderer. The command-line reference shows the resolved values printed by the command and its available options.

Review dependency versions¶

Review versions without contacting package indexes:

prodockit pins --check --offline

This checks every declaration in the root requirements files, including testrequirements.txt, and the Python version used by the hosted builds. If the project has a .prodockit-shared-files.toml manifest, the same command also checks that each declared file matches the copy supplied by the installed Prodockit release. The check changes nothing.

For example, the Prodockit documentation repositories share managed website and PDF styles in pdk.css and pdk-pdf.css, plus shared website behaviour in pdk.js. Preview a missing or different copy directly with:

prodockit shared-files --check

Restore the installed release's copy only when you intend to review the result:

prodockit shared-files --apply
git diff -- docs/stylesheets/pdk.css docs/stylesheets/pdk-pdf.css docs/javascripts/pdk.js

Commit the restored file only after reviewing the difference. The shared-file check reads the installed package and the local project; it does not contact a package index or another repository.

Use the interactive command only when you intend to review and take an update:

prodockit pins

Changing a pin is not proof the new output is equivalent. Keep the earlier PDF and website, rebuild with the proposed versions, compare them, and run the tests. The version pinning guide explains managed packages and non-Python inputs such as Pandoc and runner images.

Use one maintenance cycle¶

For a planned maintenance change:

Preview shared template changes
```
prodockit template-sync
```
Check declared versions and shared files
```
prodockit pins --check --offline
```
Apply only the update you intend to review

Use prodockit template-sync --apply for a template update or prodockit pins for an independent dependency update. Template sync already aligns the versions and supported toolchain declared by the selected template, so do not run a separate pin update unless it is intentional and will be reviewed with the same release.

Rebuild and test

zensical build --clean --strict
prodockit pdf

Review before committing

Inspect git diff, compare the website and PDF, then commit only when the change is understood.

Publishing¶

The Publishing workflow is supplied for both repository hosts:

.github/workflows/docs.yml builds and publishes through GitHub Actions.
.gitlab-ci.yml builds and publishes through GitLab CI/CD.

Both install dependencies, build the PDF and website, run the project's supplied checks, and publish Pages. In normal use you push the source and let the selected host run the supplied pipeline; you do not upload public/ manually.

After pushing:

Open the repository's Actions or Pipelines page.
Wait for the complete pipeline, not only its build job.
Open the published site from the Pages settings.
Check the release marker, PDF download, maths, diagrams, and recent content.

The publishing guide explains the supplied workflows. The continuous-integration reference covers full Git history, release rebuilds, deployment concurrency, runners, and custom pipelines.

Mirror to a second host¶

mirroring is needed only when the project genuinely needs to publish from two hosts. Add the second repository as another remote:

git remote add mirror <ssh-url-of-second-repository>
git remote -v

To update it, fetch release tags and push the tags before the branch so the mirror's build can display the correct release:

git pull origin main
git fetch origin --tags
git push mirror --tags
git push mirror main

Use SSH URLs and ensure the key for the second host is configured before starting. Confirm the mirror's own pipeline and Pages site after every sync.

Checks worth having¶

Run these checks before publishing a release or after changing build configuration:

prodockit sync-repo --check
prodockit pins --check --offline
prodockit config --check
zensical build --clean --strict
prodockit pdf

sync-repo --check detects repository metadata that no longer matches the actual remote.
pins --check --offline detects inconsistent declared versions.
config --check reports invalid Prodockit settings and missing local files, navigation pages, images, citation styles, extensions, or renderers.
The builds prove both outputs can be generated from a clean website tree.

Then inspect the website and PDF. Check navigation, references, captions, diagrams, maths, page breaks, fonts, links, and the latest changed content. Authors normally rely on the supplied publishing pipeline for its automated checks. Maintainers who need to run or extend that test suite should use the testing guidance in the prodockit reference manual.

Where to go next¶

Build and inspect both outputs before publishing or submitting. Return to the prodockit reference manual for command-line details, PDF options, or publishing configuration.