Installation¶

Requirements¶

Python 3.10 or later. Tested on 3.10, 3.11, 3.12 and 3.13; pip will refuse to install on anything older rather than failing later at import.

Everything below is pulled in automatically by pip install prodockit, except where noted:

The floors above are the ones declared in pyproject.toml, and a test keeps this table in step with them - the two had drifted apart, with Markdown recorded here as >= 3.4 long after the real floor moved to 3.10.3 (prodockit-extensions#372).

Not installed by pip¶

These are the ones pip install prodockit does not bring, and they differ in kind:

The citation style is a download rather than an install. Pandoc resolves harvard-cite-them-right.csl from the directory it runs in, and every CI script here fetches it immediately before building:

curl -fsSL -o harvard-cite-them-right.csl "https://www.zotero.org/styles/harvard-cite-them-right"

It is deliberately not committed: it is third-party content with its own licence and its own release cadence, and a vendored copy would go stale silently while every build kept succeeding. prodockit bootstrap fetches it for you, and .gitignore keeps a local copy out of commits.

weasyprint is worth separating from pandoc rather than filing both as "external binaries": one is a pip install away and the other is not, and a reader who treats them alike goes looking for a package that does not exist, or misses one that does.

Pandoc is version-sensitive in a way that changes output rather than breaking the build: a major version below 3 renders code blocks as justified prose, and the builds pin an exact release because two 3.x versions have already disagreed about the same source. prodockit bootstrap installs the pinned version where a package manager allows it and tells you when your local pandoc differs - see Pinning build inputs.

See PDF generation for how prodockit.pdf locates these, and Known limitations for why the Node ones are needed at all. A build with neither Mermaid diagrams nor maths needs neither of them, and no browser.

From PyPI¶

pip install prodockit

For a minimal project that needs no PDF toolchain, continue with Build your first site. The external tools above can be added later when the document needs their features.

Enabling an extension¶

Each prodockit extension is registered as a standard Python-Markdown extension under the markdown.extensions entry point group, so it can be enabled by name, the same way you'd enable a built-in extension like toc or a pymdownx one:

import markdown

html = markdown.markdown(
    text,
    extensions=["prodockit.headings", "prodockit.refs", "prodockit.tables"],
)

Or, for a Zensical project, in zensical.toml alongside the built-in and pymdownx extensions. Unlike pymdownx's and Zensical's own namespaces, Zensical doesn't hoist a nested prodockit.headings table into that dotted extension name, so each one needs a quoted key instead:

[project.markdown_extensions."prodockit.headings"]
[project.markdown_extensions."prodockit.refs"]
[project.markdown_extensions."prodockit.citations"]
[project.markdown_extensions."prodockit.glossary"]
[project.markdown_extensions."prodockit.tables"]
[project.markdown_extensions."prodockit.tree"]
[project.markdown_extensions."prodockit.steps"]
[project.markdown_extensions."prodockit.bibliography"]
[project.markdown_extensions."prodockit.index"]

Enable only the ones you use - each is independent, and none of them requires another.

The nine extensions¶

See each extension's own page for its syntax, examples, and configuration:

What is not an extension¶

Several parts of prodockit have no markdown.extensions entry point and nothing to add to zensical.toml, because they are not Markdown syntax:

Contributors changing the package itself should use the editable installation and repository checks in Development and code map.