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 |
| 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.13:
python -m pip install prodockit
The base installation includes Zensical, Python-Markdown, PyMdown Extensions, and the other Python libraries used by the Markdown extensions. Optional extras add features with larger testing or indexing dependencies:
python -m pip install "prodockit[index]" # PDF back-of-book index
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:
- install WeasyPrint with
python -m pip install weasyprintand install its native Pango libraries; - install Pandoc for PDF generation and BibTeX/BibLaTeX bibliographies; and
- install the optional Node tools and Chrome or Chromium only when the PDF contains Mermaid diagrams or TeX maths.
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 bootstrap |
Check or prepare a machine and document project |
prodockit init-tools |
Install the local Node tooling for Mermaid and maths rendering |
prodockit init-mathjax |
Copy the installed MathJax bundle into website assets |
prodockit pdf |
Build one PDF from the pages in 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:
prodockit pdf
zensical build --clean --strict
The PDF comes first because the site build copies the completed PDF into its output. The maintained template includes annotated GitHub Actions and GitLab CI workflows that perform the same clean 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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file prodockit-0.42.0.tar.gz.
File metadata
- Download URL: prodockit-0.42.0.tar.gz
- Upload date:
- Size: 2.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
09d98831ec643f98183926c446ed5a26c97c6cb438e5321eb813c6a0b71a124a
|
|
| MD5 |
00987cbcb868295fda4e5c2fef59c91b
|
|
| BLAKE2b-256 |
d5e453a39521b74da3ad7d7f01a0c9e524be84e66db0a768f5faa4cd371e9ead
|
Provenance
The following attestation bundles were made for prodockit-0.42.0.tar.gz:
Publisher:
publish.yml on buckwem/prodockit-extensions
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
prodockit-0.42.0.tar.gz -
Subject digest:
09d98831ec643f98183926c446ed5a26c97c6cb438e5321eb813c6a0b71a124a - Sigstore transparency entry: 2561689498
- Sigstore integration time:
-
Permalink:
buckwem/prodockit-extensions@371d0b6065cb32cbcd4bca1d768bce727182cbc1 -
Branch / Tag:
refs/tags/prodockit-v0.42.0 - Owner: https://github.com/buckwem
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@371d0b6065cb32cbcd4bca1d768bce727182cbc1 -
Trigger Event:
release
-
Statement type:
File details
Details for the file prodockit-0.42.0-py3-none-any.whl.
File metadata
- Download URL: prodockit-0.42.0-py3-none-any.whl
- Upload date:
- Size: 309.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1c8b0df7c5d2f2ad8ea26e527b3b32dc25752a1a841348b7e8419b5125101810
|
|
| MD5 |
02efab75f61d0b8a28ddd7a8244286f7
|
|
| BLAKE2b-256 |
207197aaf40ec2ea4a5c030b8eeab27f44fa4355f91615c966f49ab7e236ab52
|
Provenance
The following attestation bundles were made for prodockit-0.42.0-py3-none-any.whl:
Publisher:
publish.yml on buckwem/prodockit-extensions
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
prodockit-0.42.0-py3-none-any.whl -
Subject digest:
1c8b0df7c5d2f2ad8ea26e527b3b32dc25752a1a841348b7e8419b5125101810 - Sigstore transparency entry: 2561690023
- Sigstore integration time:
-
Permalink:
buckwem/prodockit-extensions@371d0b6065cb32cbcd4bca1d768bce727182cbc1 -
Branch / Tag:
refs/tags/prodockit-v0.42.0 - Owner: https://github.com/buckwem
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@371d0b6065cb32cbcd4bca1d768bce727182cbc1 -
Trigger Event:
release
-
Statement type:
