prodockit
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.pdf, andprodockit.zensical_macrosare implemented and tested.
Installation
pip install prodockit
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 - similar in spirit to LaTeX's \ref. |
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 |
Percentage or fixed column widths on a table, via a width attribute already attachable to a header 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. |
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 - the heading's current
section number; \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.
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.
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.
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.11.0.tar.gz.
File metadata
- Download URL: prodockit-0.11.0.tar.gz
- Upload date:
- Size: 753.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dfb692ce2e2bacdc51c4a304741177ff01ebf298135978c4028c337c4404b9dd
|
|
| MD5 |
8a99ed31fd340d6c1eb813952560d610
|
|
| BLAKE2b-256 |
45c3c231a2434e865bd33ba623cf98d5178911a136f3182ff3ce4bb9ff815a30
|
Provenance
The following attestation bundles were made for prodockit-0.11.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.11.0.tar.gz -
Subject digest:
dfb692ce2e2bacdc51c4a304741177ff01ebf298135978c4028c337c4404b9dd - Sigstore transparency entry: 2257283579
- Sigstore integration time:
-
Permalink:
buckwem/prodockit-extensions@8f4a1a7ae1f268745697a91f377b90c879b4c16a -
Branch / Tag:
refs/tags/prodockit-v0.11.0 - Owner: https://github.com/buckwem
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@8f4a1a7ae1f268745697a91f377b90c879b4c16a -
Trigger Event:
release
-
Statement type:
File details
Details for the file prodockit-0.11.0-py3-none-any.whl.
File metadata
- Download URL: prodockit-0.11.0-py3-none-any.whl
- Upload date:
- Size: 117.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
79efa0893dbce7ca3ab904123c50bd5a573fc3112e7e18c19044290ef263cd0a
|
|
| MD5 |
ed7841fa77700aa051ce989aad408a84
|
|
| BLAKE2b-256 |
526c610ab8863e2a39916025a1d7dd31628c2277163d7b0b6deba5d925b0410a
|
Provenance
The following attestation bundles were made for prodockit-0.11.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.11.0-py3-none-any.whl -
Subject digest:
79efa0893dbce7ca3ab904123c50bd5a573fc3112e7e18c19044290ef263cd0a - Sigstore transparency entry: 2257283595
- Sigstore integration time:
-
Permalink:
buckwem/prodockit-extensions@8f4a1a7ae1f268745697a91f377b90c879b4c16a -
Branch / Tag:
refs/tags/prodockit-v0.11.0 - Owner: https://github.com/buckwem
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@8f4a1a7ae1f268745697a91f377b90c879b4c16a -
Trigger Event:
release
-
Statement type:
