prodockit
A toolkit for writing and publishing professional or academic documents with Zensical. Write the content once in Markdown, publish it as a website, and build a single downloadable or submittable PDF from the same pages and navigation.
prodockit combines:
- nine Python-Markdown authoring extensions for headings, references, citations, glossaries, tables, directories, procedures, bibliographies, and indexes;
- a Pandoc and WeasyPrint PDF pipeline;
- Zensical macros and built-output tests; and
- commands for machine setup, template updates, repository metadata, and reproducible build inputs.
PyMdown Extensions is a
direct part of the authoring foundation. prodockit.steps and
prodockit.tree are built with the PyMdown Blocks API, so they use its
slash-fenced block model rather than a separate, look-alike parser.
Choose where to start
| You want to | Start here |
|---|---|
| Create and publish a document | prodockit User Guide |
| Begin with a maintained report project | prodockit-template |
| Use Adoption to add prodockit to an existing Zensical document | prodockit adopt |
| Choose and install each dependency directly | Manual installation |
| Build a small local site from scratch | Build your first site |
| Look up Markdown syntax and configuration | Authoring reference |
| Build a PDF or publish with CI | Publish a document |
| Evaluate versions, platforms, and maturity | Support and compatibility |
| Change prodockit itself | Contributing |
Project status
prodockit is currently Alpha: its documented features are functional and tested, but pre-1.0 releases can still make a documented breaking change when needed to regularise the public configuration.
Bootstrap has completed manual end-to-end testing on Ubuntu, Windows, and macOS against both the University of Surrey GitLab and GitHub.com. That testing covered creating a new document repository and installing an existing online repository locally. The full test suite runs on Ubuntu for every push and pull request and is also run locally on macOS. Windows has manual workflow coverage, but not a hosted full-suite regression job.
See Support and compatibility for the precise test depth, supported versions, and known constraints.
Installation
prodockit requires Python 3.10 or later and is tested on Python 3.10–3.14:
python -m pip install prodockit
The base installation includes Zensical, Python-Markdown, PyMdown Extensions, and the other Python libraries used by the Markdown extensions. The testing extra adds the larger dependencies used to inspect generated artifacts:
python -m pip install "prodockit[testing]" # checks for a built site and PDF
PDF and bibliography features need tools that the base installation does not supply:
- on Windows x64, let
pdk pdfacquire its verified project-local WeasyPrint runtime; on macOS and Linux it installs the committedpdf-requirements.txton first use, while native Pango remains an operating-system prerequisite; - let
pdk pdfadd PyMuPDF only when a back-of-book index is enabled; - let
pdk pdfacquire verified project-local Pandoc and PDF fonts on first use; and - install Node.js only when a PDF contains TeX maths; ProDockit transparently caches MathJax 4 without npm, while Mermaid remains Python-only.
Follow the complete, platform-specific installation guide before building a PDF. Check the installed release with:
prodockit --version
Authoring extensions
Enable only the extensions a project uses in zensical.toml. Each extension
has a beginner-first guide with copyable Markdown and a rendered result.
| Extension | Use it for |
|---|---|
prodockit.headings |
Numbered headings and appendices |
prodockit.refs |
Cross-references to headings, figures, and tables |
prodockit.citations |
A small reference list written directly in Markdown |
prodockit.glossary |
Acronyms and glossary terms |
prodockit.tables |
Widths, merged cells, dense tables, and richer headers |
prodockit.tree |
Readable directory trees |
prodockit.steps |
Procedures presented as numbered steps |
prodockit.bibliography |
BibTeX/BibLaTeX citations formatted with CSL |
prodockit.index |
A PDF-only back-of-book index |
For example:
[project.markdown_extensions."prodockit.headings"]
numbering = "continuous"
[project.markdown_extensions."prodockit.refs"]
[project.markdown_extensions."prodockit.steps"]
The authoring reference explains the three consistent stages for each feature: enable the extension, write the Markdown, then configure optional behaviour.
Publishing and project commands
Run prodockit --help for the options installed with the current release.
The pdk executable is an exact shorter alias for prodockit; boot aliases
bootstrap, and source aliases source-bundle.
| Command | Purpose |
|---|---|
prodockit diag |
Diagnose without changing anything by default; preview or explicitly confirm bounded repairs |
prodockit config |
Show resolved Prodockit settings and check source-project integrity |
prodockit adopt |
Add selected prodockit components to an existing Zensical document |
prodockit bootstrap |
Check or prepare a machine and a project based on prodockit-template |
prodockit update-dates |
Add per-page revision dates to a completed website without changing Markdown source |
prodockit pdf |
Validate built markup and website maths, then build one PDF from the Zensical navigation |
prodockit source-bundle |
Bundle the Markdown source and configuration into a separate PDF |
prodockit sync-repo |
Match repository links, branding, and managed README badges to origin |
prodockit pins |
Check and update build-input versions across project files |
prodockit template-sync |
Review and apply later updates from prodockit-template |
The command-line reference documents safe first runs, write behaviour, and aliases. When publishing both outputs locally, build in this order:
zensical build --clean --strict
prodockit pdf
prodockit update-dates
The PDF consumes the completed Zensical site and does not invoke the site
builder. Mermaid and MathJax PDF runtimes are prepared transparently in the
project cache; maths currently needs Node.js but neither renderer needs npm or
a browser. prodockit update-dates post-processes the
generated HTML and does not edit the files you author or call the site builder.
It is also a standalone
capability: an existing Zensical project can use it after installing
the package, without running prodockit adopt or enabling any other Prodockit component. The maintained
template includes annotated GitHub Actions and GitLab CI workflows that
perform the same build, test the generated files, and deploy Pages.
Package integrations
| Integration | Purpose |
|---|---|
prodockit.zensical_macros |
Word counts, repository data, document-wide numbering, and layout helpers for Zensical templates |
prodockit.testing |
Reusable pytest fixtures and checks for a generated site and PDF |
These are not Markdown extensions. Macros are enabled through Zensical's
macros configuration; testing support is installed with
python -m pip install "prodockit[testing]".
Development
Changes to the package, tests, automation, or technical documentation should follow CONTRIBUTING.md. It gives the editable installation, external PDF prerequisites, macOS library-path setup, source gates, built-site tests, and pull-request expectations.
Contributing
Contributions are welcome. Search or open an issue before starting a change beyond a small correction, and submit changes through a focused branch and pull request. See Contributing for the complete workflow.
Licence
MIT - see LICENSE.
1 maintainer
Release files for prodockit 0.71.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| prodockit-0.71.0.tar.gz | 8.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| prodockit-0.71.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 9.1 MB
Release files / prodockit-0.71.0.tar.gz
| Download URL | prodockit-0.71.0.tar.gz |
|---|---|
| Size | 8.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a55b8c961058e555ef4980470bda3665beadd26c28f5f5f8401cc58cd3fd21a
|
|
BLAKE2b-256 checksum How to use checksums |
163aceceb02d223813cc2765af4f523f82370f1bf027d8e8185d87222472c660
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / prodockit-0.71.0-py3-none-any.whl
| Download URL | prodockit-0.71.0-py3-none-any.whl |
|---|---|
| Size | 568.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b842826c3c4dc15e13b029d4503dbfe95be87c9a67eba94508d15c7ded678836
|
|
BLAKE2b-256 checksum How to use checksums |
41c53a6045842e383a012caeff42c570a23ae64975c0361bfa50eb884a2487c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency log
