Customise build¶

Customisation covers changing your document. This page covers changing how it gets built and published - the two build commands, the optional tooling some features need, and the settings that make publishing behave correctly.

The two build commands¶

Your project produces two outputs from the same source, and each has its own command:

prodockit pdf      # builds the PDF
zensical build     # builds the website

Both read the same zensical.toml, so your zensical.toml nav, fonts, page size and settings apply to both. The website is rendered by Zensical directly; the PDF goes through Pandoc and WeasyPrint instead.

That second path is the source of most of what follows. WeasyPrint has no JavaScript engine, so anything your website renders in the browser - diagrams, mathematical notation - has to be turned into a static image before the PDF is built.

Diagrams and maths¶

Diagrams work on the website with no setup: Mermaid.js is part of Zensical's own bundle, and runs in the reader's browser. Maths does not - MathJax is installed, not committed (it's third-party code, and a repository is redistribution), so a formula renders as raw TeX on the website too until it's been installed once. Neither works in the PDF at all: WeasyPrint has no JavaScript engine, so prodockit pdf pre-renders both to images using two Node.js tools.

Set them up once. Which commands you need depends on where your project came from:

From the template, the tools/mermaid and tools/mathjax manifests and lockfiles are already tracked, so you only install them:

npm ci --prefix tools/mermaid
npm ci --prefix tools/mathjax

This is the case for most readers, and Install the diagram and maths tooling walks through it alongside installing Node.js itself - including the extra step Maths needs afterwards, to install the MathJax bundle and config the website uses (not just the PDF pre-render above).

Starting a project from scratch, you have no tools/ directory yet, so create it first:

prodockit init-tools
npm ci --prefix tools/mermaid
npm ci --prefix tools/mathjax

prodockit init-tools writes the tools/mermaid and tools/mathjax directories, then prints the install commands and the settings a CI pipeline needs. Commit the manifests and lockfiles it creates; the node_modules/ directories are ignored. Still install the MathJax bundle itself afterwards, the same way.

A project using neither diagrams nor maths can skip this section entirely.

Fonts¶

Your website loads its fonts from a CDN when a reader opens the page. The PDF cannot: WeasyPrint has to embed the actual font files, so they must be installed on whatever machine builds the PDF.

If they are missing, WeasyPrint substitutes a default font without warning. The PDF builds, publishes, and simply looks wrong.

The fonts to install are whichever ones zensical.toml names - see Fonts for that setting. Left unset, they are Inter Inter for body text and JetBrains Mono JetBrains Mono for code, which is what the examples below use.

What format to install¶

Install the desktop font files - .ttf (TrueType) or .otf (OpenType). Both work equally well.

Where to install them¶

Your CI runner needs them too, and starts from a bare image every run - see the fonts-inter fonts-jetbrains-mono line in Publishing below.

Check they were actually used¶

Since a missing font produces a PDF rather than an error, the only reliable check is to look at what the finished document actually embedded:

python -c "
import pymupdf
d = pymupdf.open('docs/site_documentation.pdf')
print(sorted({f[3].split('+')[-1] for p in d for f in p.get_fonts()}))
"

pymupdf is already installed - it comes with the [index] extra in requirements.txt. Run against this guide's own PDF, it prints:

['Inter', 'Inter-Bold', 'Inter-Italic', 'Inter-Ultra-Bold',
 'JetBrains-Mono', 'JetBrains-Mono-Bold', 'Trebuchet-MS']

The configured fonts, in whichever weights the document happens to use. A name you did not configure appearing there is the substitution happening - a PDF built without Inter installed shows a default serif or sans face in its place instead.

Pinning build inputs¶

Your document has more inputs than its own content. Zensical renders the site, Pandoc and WeasyPrint lay out the PDF, and whatever runs the pipeline carries its own OS image. Left unpinned, an upgrade to any of them doesn't fail the build - it just quietly publishes a slightly different document, with nothing to indicate anything changed.

prodockit pins keeps these declarations - a version in requirements.txt, a PANDOC_VERSION in a workflow file, a runner label - in step with each other, wherever they're written down:

prodockit pins          # prompt per package; Enter takes the newest release
prodockit pins --check  # behind, or files disagreeing with each other? exit non-zero

With no -p flags, both commands cover five packages by default: zensical, weasyprint, markdown, pymdown-extensions, and pandoc - Pandoc is the fourth build input alongside Zensical and WeasyPrint, and the one that has actually caught this project family out. Pandoc 3.10 stopped treating a syntax-highlighted <pre><code> as a code block; on that version every fenced code block in the PDF lost its preformatting and reflowed as justified prose, while the build reported success. The published PDFs stayed correct only because CI happened to be installing an older pandoc than anyone's laptop - exactly the silent drift this section exists to catch. Pandoc version drift covers the how, and prodockit's limitations page records the episode in full.

This project pins zensical/weasyprint in requirements.txt, and pandoc as PANDOC_VERSION in both .github/workflows/docs.yml and .gitlab-ci.yml:

$ prodockit pins --check
zensical
  requirements.txt:12  zensical==0.0.53
  newest on PyPI: 0.0.53
...
pandoc
  .gitlab-ci.yml:52  PANDOC_VERSION: "3.10.1
  .gitlab-ci.yml:139  PANDOC_VERSION: "3.10.1
  .github/workflows/docs.yml:50  PANDOC_VERSION: "3.10.1
  not on PyPI - set the version yourself
Every managed package is current and consistent.

"Not on PyPI" is the one way pandoc's entry differs from the rest: it isn't a Python package, so there's no release index to check against or take "newest" from - prodockit pins (no --check) still prompts for it like any other package, but you type the version rather than pressing Enter for the newest. --set works exactly the same as anywhere else:

prodockit pins --set pandoc=3.10.1

This project also pins the runner/image used to build it - ubuntu-24.04 in .github/workflows/docs.yml, python:3.13 in .gitlab-ci.yml - since a runner label or image tag has no package index either, only --set to a version you choose yourself, e.g. prodockit pins -p ubuntu --set ubuntu=24.04.

prodockit itself uses a minimum version rather than an exact pin: this userguide requires 0.41.0 or newer because that release introduced the extension-owned back-of-book index configuration. It isn't one of prodockit pins' five default packages, so managing or checking that floor needs naming explicitly:

prodockit pins --check -p zensical -p weasyprint -p prodockit

Watching for drift¶

A newer release existing isn't interesting on its own - PyPI already answers that. Whether taking it would change what gets published is the thing worth someone looking at, and the only way to answer that is a real build: with the pinned versions, then again with the newest ones, diffed byte for byte.

Both .github/workflows/drift.yml and the drift job in .gitlab-ci.yml do exactly this, weekly:

build (pinned) → build (newest) → diff the PDF and website → report

It reports rather than fails - allow_failure: true on GitLab, and the GitHub job skips its own report step entirely once nothing actually changed - and keeps a single open issue updated in place rather than filing a fresh one every week. A build order flip here (zensical build after prodockit pdf, not before) matters more than it looks: zensical build copies the PDF into the published site, so building it first would make every comparison a false positive that looks exactly like drift.

All three pinned packages are watched, not just Zensical and WeasyPrint - prodockit is upgraded and reported alongside them, since it renders content directly and can change output the same way.

Taking an upgrade¶

When a drift issue reports something worth having:

prodockit pins -p zensical -p weasyprint -p prodockit  # accept the suggested version, or type one
prodockit pdf                                          # rebuild - PDF first ...
zensical build --clean --strict                        # ... then the site

Then diff the built output against the previous version before committing - the same comparison the drift job already made, just with a person deciding rather than reading a report. Repeat for the runner image if that's what moved (prodockit pins -p ubuntu, or -p python on GitLab), since it isn't upgraded by the same command.

See prodockit-extensions' own Taking an upgrade and Version pinning and drift sections for the full reasoning behind each step - this project's two files are that same recipe, adapted from a pyproject.toml-based Python package to a requirements.txt-based Zensical site.

Publishing¶

This project publishes from two pipelines, kept deliberately in step:

• .github/workflows/docs.yml — GitHub Actions, publishing to GitHub Pages.
• .gitlab-ci.yml — GitLab CI/CD, publishing to GitLab Pages, for a mirrored copy.

Both install the same tooling and run the same commands, in the same order:

install dependencies → prodockit pdf → zensical build --clean --strict → run tests → publish

The tests run after both builds because they check the built output - a diagram that reached the PDF as raw source fails the pipeline rather than being published.

The GitHub pipeline has one further step the GitLab one does not: after publishing, it polls the live site and fails the run if the page it fetches doesn't match what was just deployed. A successful deploy is not proof the site is actually serving it - GitHub Pages has, more than once, reported success and quietly kept serving the previous build.

Four settings that are easy to get wrong¶

Each of these is invisible when wrong: nothing fails, the site just publishes something incorrect.

Full git history. The cover page's release number comes from git describe --tags. Both GitHub Actions and GitLab CI clone shallowly by default, which fetches no tags at all, so the release line silently disappears - while working perfectly on your own machine, where you have the full history.

# GitHub Actions
- uses: actions/checkout@v5
  with:
    fetch-depth: 0

# GitLab CI
variables:
  GIT_DEPTH: "0"

Rebuild when a release is published - but not from the tag. A release is normally tagged after the commit is pushed, and that push is what triggers the deploy, so the first deploy after a release still shows the previous version. Something has to rebuild once the tag exists.

The obvious answer - trigger the deploy on the tag as well - is the wrong one, and fails quietly on both hosts. On GitHub, a Pages deployment carrying a tag ref is accepted, reported successful, and then never served (issue #43). On GitLab it is served, but it publishes whatever the tag points at, which is older than main whenever a release has been overtaken by newer commits (issue #58).

So neither pipeline builds tags. GitHub rebuilds against main from a separate redeploy-after-release.yml workflow; the GitLab mirror gets the same result from pushing tags before the branch, as in Mirroring to a second host below.

One deploy at a time. Publishing a release shortly after merging its version bump starts two deploys at once, and they race. The one that finishes last does not necessarily win - so the site can end up serving the older build, with nothing reporting a problem. GitHub uses a concurrency group; GitLab uses resource_group.

The Puppeteer variable. mermaid-cli drives Chrome through Puppeteer to draw diagrams. Set PUPPETEER_SKIP_DOWNLOAD, not the older PUPPETEER_SKIP_CHROMIUM_DOWNLOAD - Puppeteer renamed it, and the current version ignores the old name, downloading a full Chrome build on every run before discarding it.

Mirroring to a second host¶

Both pipelines above assume your code already exists on both hosts. Getting it there in the first place - and keeping it there as you keep writing - is a separate, one-off step: a plain remote operation, nothing platform-specific. A remote is just a name pointing at a URL; a repository can have as many as it likes, on as many different hosts as it likes, regardless of which one you originally cloned from.

Add the second host as a new remote (once):

git remote add mirror <url-of-the-second-host's-copy-of-this-repo>

Then, whenever you want to bring the mirror up to date with whatever you've pushed to your primary host:

git pull origin main    # bring your local main up to date with your primary host
git push mirror --tags  # release tags first, so the build below can see them
git push mirror main    # then the branch - this is the push that publishes

That last push is what triggers the mirror's own CI/CD pipeline - see Publishing above. There's nothing to automate here unless you want to: pushing a fresh copy up before or after a release is a manual step, the same size as any other Git command.

git fetch origin --tags
git describe --tags --abbrev=0   # should show the release you just made

GitHub to GitHub¶

Mirroring between two GitHub-hosted copies - your own account and an organisation's, say, or two separate GitHub instances - looks like:

git remote add mirror git@github.com:your-org/your-repo.git
git pull origin main
git fetch origin --tags
git push mirror --tags
git push mirror main

GitHub to GitLab¶

Mirroring to a GitLab instance - an institution's own self-hosted instance, or GitLab.com - is exactly the same pattern, just a different host in the URL:

git remote add mirror git@gitlab.example.org:your-namespace/your-repo.git
git pull origin main
git fetch origin --tags
git push mirror --tags
git push mirror main

Confirm both remotes are set up correctly at any point with git remote -v.

Checks worth having¶

Three commands turn the quiet failures above into loud ones:

prodockit sync-repo --check   # config drifted from your git remote?
prodockit pins --check        # build inputs behind PyPI, or pinned inconsistently?
python -m pytest test/        # diagrams, maths and links in the built output

prodockit sync-repo --check writes nothing and exits non-zero if your repository links, header icon or README badges no longer match the remote you are actually publishing from - useful after forking or moving a project. prodockit pins --check does the same for the pins in Pinning build inputs above. See Testing for the third.

Where to go next¶

Continue to Additional tooling for optional extras - VS Code extensions, GitLens, and Vale - or see Testing for the checks that guard the failures described above.