prodockit

Documentation Build GitHub Stars GitHub Forks

A family of extensions for Zensical needed for professional and academic documentation: section cross-references, bibliography/citation handling, a glossary, and a Pandoc/WeasyPrint PDF pipeline for the downloadable, submittable document these usually need alongside the website itself.

Most of prodockit is Python-Markdown extensions, enabled in zensical.toml. prodockit.pdf is a command-line tool instead (prodockit pdf), since a PDF build pipeline isn't a Markdown syntax extension - it reads the same zensical.toml too. In addition, there's a set of website macros (prodockit.zensical_macros) to help use prodockit's features.

It's a kit for professional documentation, built on Zensical's own Markdown and Pandoc/WeasyPrint PDF pipeline.

Status: early, but functional - prodockit.headings, prodockit.refs, prodockit.citations, prodockit.glossary, prodockit.tables, prodockit.bibliography, prodockit.index, prodockit.steps, prodockit.tree, prodockit.pdf, prodockit.sync_repo, prodockit.pins and prodockit.zensical_macros are implemented and tested. prodockit.bootstrap is newer, and now exercised end to end on macOS, Ubuntu and Windows against the University of Surrey's GitLab - Windows including Mermaid diagrams and TeX maths rendered into the PDF, which needs the Node toolchain as well as the Python one. github.com has been run and the faults it found are fixed, but it has not completed a clean run start to finish; gitlab.com is covered by tests rather than by a machine.

Full documentation

Installation

Requires Python 3.10 or later (tested on 3.10-3.13).

pip install prodockit

Check what you have with prodockit --version, which prints the bare number the same way zensical --version does.

prodockit.pdf and prodockit.bibliography additionally need pandoc, and the PDF build needs weasyprint - external binaries, not Python packages, so pip doesn't install them. See Installation for the full list, including the optional Node tooling for Mermaid diagrams and TeX maths in the PDF.

Extensions

Extension Description
prodockit.headings Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...).
prodockit.refs \ref{id} section cross-references, resolving to the target's current number and name - and \autoref{id}, which additionally carries the target's page number in the PDF.
prodockit.citations Define a source once, cite it by key anywhere with \citeref{id} - auto-generates the bracketed, linked citation text.
prodockit.glossary Define a term once (an acronym expansion, a glossary entry), insert it by id anywhere with \gls{id} - similar in spirit to LaTeX's glossaries package.
prodockit.tables Column widths, dense tables, headers of more than one row, merged cells and rotated headings - all through a width, .compact, .header, colspan/rowspan or rotate attribute already attachable to a cell with attr_list.
prodockit.bibliography An alternative to prodockit.citations: define sources in a BibTeX/BibLaTeX .bib file and format \cite{id}/the reference list in any Citation Style Language style, via Pandoc's own --citeproc.
prodockit.index Mark a term inline with \index{Term} for a traditional, PDF-only back-of-book index - with hierarchical sub-entries and code-styled terms.
prodockit.steps Numbered steps a reader works through in order - a number to find your place by, room for a command and its explanation, and a line joining one step to the next.
prodockit.tree A directory listing that looks like one - indentation is the structure, a trailing / marks a directory, and the icons come from the project's own set. 
import markdown

html = markdown.markdown(
    text,
    extensions=[
        "attr_list", "prodockit.headings", "prodockit.refs", "prodockit.citations", "prodockit.glossary"
    ],
)

# Introduction {: #intro }

See \ref{intro} for background.\citeref{skou2023} This uses \gls{css}.

Skoulikari, A. (2023) *Learning Git*.
{: #skou2023 data-cite-text="Skoulikari, 2023" }

**CSS** - Cascading Style Sheets.
{: #css data-term="CSS" }

\ref{intro} resolves to a link reading 1 Introduction - the heading's number and name, with \autoref{intro} additionally carrying its page number in the PDF; \citeref{skou2023} resolves to [Skoulikari, 2023], linked to that source; \gls{css} resolves to CSS, linked to its own definition. All three stay correct if content is reordered, since resolution happens fresh on every conversion. See the docs for options, multi-page registry sharing, and full syntax details.

PDF generation

prodockit.pdf builds a standalone PDF from your site, via Pandoc and WeasyPrint (both need to be installed separately - see the docs). No Python required - it reads the same zensical.toml your site already has:

prodockit pdf

That's it - run it from your project root and it builds a complete PDF, table of contents included, from every page in your nav. Also handles a table too wide for a portrait page - printed sideways, on its own landscape page(s), spanning multiple pages with a repeated heading row - {.web-only}/{.pdf-only} markers for content that should only appear in one of the two outputs, and a two-column, letter-headed back-of-book index (pdf_include_index) generated from prodockit.index's own \index{Term} markers. See the docs for the zensical.toml settings it reads, and for the Python API (build_pdf(), prodockit.pdf.html/.lua/.css/.icons/.mermaid/.rotate) if you're scripting your own build pipeline instead.

prodockit source-bundle builds a second, separate PDF - your Markdown content and zensical.toml, one file per page, into docs_dir - for a submission that needs the underlying source alongside the document itself:

prodockit source-bundle

A separate command from prodockit pdf, so a project that wants only one of the two PDFs doesn't build the other on every run.

Machine setup

prodockit bootstrap turns the User Guide's install sequence into twenty-three stages that can each be checked and repaired individually - prodockit's own environment, editor, git, SSH, clone, remote, commit identity, pandoc, Node - rather than a long list followed top to bottom and hoped over:

prodockit bootstrap            # report what is set up; changes nothing
prodockit bootstrap --dry-run  # print the exact commands it would run
prodockit bootstrap --apply    # set up what needs it, asking first

It cannot be the first thing you run - it is a prodockit command, so Python and pip install prodockit come first. Two steps need a human at a browser (uploading an SSH key, creating your own project); those are guided and then verified, rather than automated with a token. Currently implements the University of Surrey's GitLab, gitlab.com and github.com.

Website macros

prodockit.zensical_macros provides a site-wide word count, the git-detected repository URL, the latest release tag, chapter/appendix numbering that continues across pages, and reference/acronym/glossary spacing that matches prodockit.pdf's own PDF output - as Jinja variables/macros for Zensical's own macros plugin:

[project.markdown_extensions.zensical.extensions.macros]
modules = ["prodockit.zensical_macros"]

See the docs for the full variable/macro list.

Repository metadata

prodockit sync-repo keeps repo_url, repo_name, the header brand icon, edit_uri, site_url and your README's badge row matching the git remote your checkout actually uses - so forking or mirroring a project between GitHub, GitLab and Bitbucket doesn't leave stale links, the wrong icon, or a canonical URL pointing at the old host behind:

prodockit sync-repo          # update everything from `origin`
prodockit sync-repo --check  # report drift and exit non-zero, for CI

It also sets edit_uri explicitly, which fixes the "edit this page" button on a self-hosted GitLab and stops it pointing at a master branch that may not exist.

Staying in step with the template

A project generated from a template is a copy, not a link. It starts ageing the moment it is created - the template gains a CI fix, a stylesheet rule, a newer pin - and nothing tells you, because nothing breaks. The site still builds; the document just looks slightly unlike everyone else's. prodockit template-sync updates the template's own files and leaves your writing alone:

prodockit template-sync          # report; writes no project file
prodockit template-sync --apply  # branch, write, stage - the commit is yours

What it will and will not write is decided by a manifest in the template. The report, its figures and its bibliography are never written and never even read, so a sync cannot lose your work. A template-owned file you have edited is kept, with the template's version written beside it as .new to compare.

The template is fetched into a per-user cache, so you need no checkout of it - and a host that cannot be reached is answered with the cached copy and a warning that it may be behind, rather than a failure. Built to be run repeatedly through a project: a run with nothing to do says so and creates no branch.

Version pinning and drift

A documentation build has more inputs than its own source: zensical renders the site, weasyprint lays out the PDF, and the CI runner image carries pandoc, the fonts and Chrome. Left unpinned, an upgrade doesn't fail the build - it quietly publishes a different document.

Pinning them means declaring the same version in several files at once, which nothing keeps in step. prodockit pins finds every declaration and moves them together, keeping each one's own operator so a library floor stays a floor and a build pin stays exact:

prodockit pins               # prompt per package; Enter takes the newest
prodockit pins --check       # behind PyPI, or files disagreeing? exit non-zero
prodockit pins -p ubuntu     # runner images and container tags too

Pandoc is managed by default too - not a pip package, so it's matched as a PANDOC_VERSION CI variable rather than a specifier.

It reads pyproject.toml, GitHub Actions workflows, .gitlab-ci.yml and requirements/constraints files, so the same command works on either host. The docs also carry a weekly drift job for GitHub Actions and GitLab CI that rebuilds with the newest versions, diffs the output byte for byte, and opens an issue when an upgrade would change what you publish.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

zensical is a core dependency, so zensical serve is available as soon as prodockit is installed - no extra step needed to build the documentation locally.

Contributing

Contributions are welcome - see CONTRIBUTING.md.

License

MIT - see LICENSE.

Project links

Data verified by PyPI on Aug 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.63.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for buckwem from gravatar.com buckwem

Credits

Author: Mark Buckwell

GitHub Statistics

Data verified by PyPI on Aug 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev index testing

Tags

extension markdown pandoc pdf python-markdown zensical

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

prodockit-0.39.0.tar.gz (2.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

prodockit-0.39.0-py3-none-any.whl (303.0 kB view details)

Uploaded Python 3

File details

Details for the file prodockit-0.39.0.tar.gz.

File metadata

  • Download URL: prodockit-0.39.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

Hashes for prodockit-0.39.0.tar.gz
Algorithm Hash digest
SHA256 ad16bdddeafb783cad07d92a8824c9b54393d7da58a311910c3ed87970974c3e
MD5 57bb458f46454183b98fe11a0553194f
BLAKE2b-256 2bd705c82a204a83255fa8f969e76a3b5610d4276a89fa1b641216160a3974c1

See more details on using hashes here.

Provenance

The following attestation bundles were made for prodockit-0.39.0.tar.gz:

Publisher: publish.yml on buckwem/prodockit-extensions

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file prodockit-0.39.0-py3-none-any.whl.

File metadata

  • Download URL: prodockit-0.39.0-py3-none-any.whl
  • Upload date:
  • Size: 303.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for prodockit-0.39.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6727892678233c7d372cc3f201aa40b4798b8c12b9140d5b5b10173b1e4778aa
MD5 10255afa71da364da65d160fc055b88b
BLAKE2b-256 21ebd1efbc4677fe9f0b2a2499d69d9fe7192c26a96d720b3b375dee2580fff5

See more details on using hashes here.

Provenance

The following attestation bundles were made for prodockit-0.39.0-py3-none-any.whl:

Publisher: publish.yml on buckwem/prodockit-extensions

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.63.0

2 files

0.62.0

2 files

0.61.6

2 files

0.61.5

2 files

0.61.3

2 files

0.61.2

2 files

0.61.1

2 files

0.61.0

2 files

0.60.4

2 files

0.60.3

2 files

0.60.2

2 files

0.60.1

2 files

0.60.0

2 files

0.59.0

2 files

0.58.0

2 files

0.57.0

2 files

0.56.0

2 files

0.55.0

2 files

0.54.1

2 files

0.54.0

2 files

0.53.0

2 files

0.52.0

2 files

0.51.4

2 files

0.51.3

2 files

0.51.2

2 files

0.51.1

2 files

0.51.0

2 files

0.50.1

2 files

0.50.0

2 files

0.49.1

2 files

0.49.0

2 files

0.48.1

2 files

0.48.0

2 files

0.47.0

2 files

0.46.0

2 files

0.45.0

2 files

0.44.0

2 files

0.43.2

2 files

0.43.1

2 files

0.43.0

2 files

0.42.1

2 files

0.42.0

2 files

0.41.0

2 files

0.40.0

2 files

This release

0.39.0 This release

2 files

0.38.0

2 files

0.37.0

2 files

0.36.4

2 files

0.36.3

2 files

0.36.2

2 files

0.36.1

2 files

0.36.0

2 files

0.35.1

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.1

2 files

0.32.0

2 files

0.31.1

2 files

0.31.0

2 files

0.30.1

2 files

0.30.0

2 files

0.29.0

2 files

0.28.1

2 files

0.28.0

2 files

0.27.0

2 files

0.26.7

2 files

0.26.6

2 files

0.26.5

2 files

0.26.4

2 files

0.26.3

2 files

0.26.2

2 files

0.26.1

2 files

0.26.0

2 files

0.25.0

2 files

0.24.1

2 files

0.24.0

2 files

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.1

2 files

0.20.0

2 files

0.19.1

2 files

0.19.0

2 files

0.18.1

2 files

0.18.0

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.0

2 files

0.15.2

2 files

0.15.1

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.10.9

2 files

0.10.8

2 files

0.10.7

2 files

0.10.6

2 files

0.10.5

2 files

0.10.4

2 files

0.10.3

2 files

0.10.2

2 files

0.10.1

2 files

0.10.0

2 files

0.9.0

2 files

0.8.1

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.8

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page