zendoc 0.8.0

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

zendoc

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. Each piece is independent, so you only pay for what you use.

Most of zendoc is Python-Markdown extensions, in the spirit of pymdown-extensions - configure one the same way as any other Zensical/pymdownx Markdown extension, via zensical.toml. zendoc.pdf is a plain function library instead, since a PDF build pipeline isn't a Markdown syntax extension.

Status: early, but functional - zendoc.headings, zendoc.refs, zendoc.citations, zendoc.glossary, and zendoc.pdf are implemented and tested.

Full documentation

Installation

pip install zendoc

Extensions

Extension	Description
zendoc.headings	Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...).
zendoc.refs	\ref{id} section cross-references, resolving to the target's current number - similar in spirit to LaTeX's \ref.
zendoc.citations	Define a source once, cite it by key anywhere with \cite{id} - auto-generates the bracketed, linked citation text.
zendoc.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.

import markdown

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

# Introduction {: #intro }

See \ref{intro} for background.\cite{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; \cite{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

zendoc.pdf builds a standalone PDF from your site's own rendered pages, via Pandoc and WeasyPrint - not a Python-Markdown extension, a plain function library. build_pdf() is a one-call wrapper: hand it your rendered pages and where you want the PDF written.

from zendoc.pdf import Page, build_pdf

build_pdf(
    [Page(docs_rel_path="index.md", html=rendered_html, is_index=True)],
    "dist/report.pdf",
)

See the docs for the full parameter list, and for the individual pieces (zendoc.pdf.html/ .lua/.css/.icons/.mermaid) if you need more control over how they fit together.

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 zendoc is installed - no extra step needed to build the documentation locally.

License

MIT - see LICENSE.