Publish automatically¶

This page is for a document author who wants a reviewed Markdown change to become a website and PDF automatically. continuous integration (CI) runs the publishing commands on a clean hosted machine after a push, then hands the static website to GitHub Pages or GitLab Pages.

You should not have to design that automation. prodockit-template supplies the maintained files; this page explains how to use them, what they build, and how to tell whether publication really succeeded.

On GitHub, GitHub Actions runs the workflow. On GitLab, the equivalent pipeline is GitLab CI.

Use the maintained automation files¶

The comments in those files explain settings that must remain beside the commands they control: pinned system tools, browser variables, fonts, build order, Pages permissions, and artifact paths. Refer to the files for exact YAML rather than copying a workflow from this guide.

Projects created from prodockit-template already contain both files. If an older template-derived project is missing later workflow fixes, preview them without writing:

prodockit template-sync

Review and apply the result using Staying in step with the template.

Publish the first change¶

1. Prove the project builds locally

   prodockit pdf
   zensical build --clean --strict
   python -m pytest
   

   Fix a local failure before pushing. CI starts from a clean machine, so it cannot repair a missing page, broken link, or failing test that is already reproducible in the checkout.

2. Confirm the publishing file is present

   GitHub PagesGitLab Pages

   Confirm .github/workflows/docs.yml exists. It should run when the repository's default branch changes and should allow a manual run for recovery.

   Confirm .gitlab-ci.yml contains a pages job. GitLab reserves the name public/ for the directory that job publishes.

   Use the maintained links above to compare a file that appears incomplete. Do not replace a customised workflow until you have reviewed the difference.

3. Push through the review gate

   git push -u origin HEAD
   

   Open a pull request or merge request. After its checks and review are complete, merge it into the branch the publishing workflow watches—normally main.

4. Watch the publishing job

   GitHub PagesGitLab Pages

   Open Actions, select Documentation, and open the run for the merged commit. Check both the deployment and later live-verification result.

   Open Build > Pipelines, select the pipeline for the merged commit, and inspect its pages job. Then use Deploy > Pages to find the published address.

5. Verify delivery as a reader

   Open the Pages address in a private browser window. Find the known change, follow a navigation link, and download the PDF from the site.

   A successful build proves an artifact was produced. A successful deployment proves the host accepted it. Opening the public result proves a reader can retrieve the intended version; these are three separate checks.

Understand the build order¶

flowchart LR
    source[Markdown and zensical.toml] --> pdf[prodockit pdf]
    pdf --> site[zensical build]
    site --> tests[Built-output tests]
    tests --> deploy[Pages deployment]
    deploy --> verify[Public verification]

The PDF is built before the website because it lives under docs/ by default. Zensical copies it into the static site together with other downloadable files. Reversing the commands can publish the PDF left by an earlier run.

Some projects also run prodockit source-bundle before Zensical. That creates a second downloadable PDF containing the Markdown and configuration rather than the rendered report.

Know what the hosted machine needs¶

The maintained workflow files install these in dependency order. A document author normally changes the content and requirements, not the operating-system recipe.

Catch failures that still produce output¶

Render diagrams and maths¶

WeasyPrint has no JavaScript engine. The PDF build therefore turns Mermaid and TeX maths into static images before Pandoc sees the pages. If either renderer is missing, the command warns but can still create a PDF.

Build-output tests make that warning enforceable:

from prodockit.testing import assert_no_unrendered_mermaid, assert_no_unrendered_tex


def test_diagrams_and_maths_rendered(prodockit_pdf_page_texts):
    assert_no_unrendered_mermaid(prodockit_pdf_page_texts)
    assert_no_unrendered_tex(prodockit_pdf_page_texts)

The template workflow uses PUPPETEER_SKIP_DOWNLOAD, not the obsolete PUPPETEER_SKIP_CHROMIUM_DOWNLOAD, and points Mermaid at the Chrome installed by the job. Keep those details in the workflow where future package updates can change them.

Check embedded fonts¶

The website can download fonts when a browser opens it. A PDF must embed fonts available on the build machine. WeasyPrint may silently substitute another font, changing appearance, line wrapping, pagination, and index page numbers.

Use the template's font packages as the starting point and add an output test when the project requires a particular typeface.

Fetch tags only when the document uses them¶

The prodockit-v0.41.0 macro reads Git tags reachable from the checked-out commit. GitHub's default shallow checkout has no tags, so the value becomes an empty string without failing the build. Set a full checkout only when the document uses tag-derived macros; the template's PDF-only {RELEASE} marker uses host release metadata instead.

Test the artifact, not only the source¶

prodockit.testing opens the generated site and PDF. Start with checks that prove the required outputs exist, then add document-specific expectations:

def test_the_pdf_was_built(prodockit_pdf):
    assert prodockit_pdf.page_count > 1


def test_the_site_has_the_cover(prodockit_soup_for):
    cover = prodockit_soup_for("index.html")
    assert cover.title is not None

The template's own sample-output checks describe its starter document and are advisory because real projects replace that content. A generated project should replace them with assertions about its own required output and decide which must gate publication. See Test the built output.

Troubleshoot a publishing run¶

Repository release numbering, dependency drift, and workflow maintenance are covered in Maintain prodockit. Existing links to the former sections above remain valid.