zendoc 0.5.0

A family of Python-Markdown extensions for section cross-references and bibliography/citation handling, built for use with Zensical

zendoc

A family of Python-Markdown extensions for section cross-references and bibliography/citation handling, in the spirit of pymdown-extensions: each extension is independent and enabled separately. Built for use with Zensical - configure it the same way as any other Zensical/pymdownx Markdown extension, via zensical.toml - but since it's a standard Python-Markdown extension, it works with any tool built on Python-Markdown (MkDocs, etc.). Factored out of zendoc-template, a Zensical project, so it can be installed and reused independently of that template.

Status: early, but functional - zendoc.headings, zendoc.refs, zendoc.citations, and zendoc.glossary are implemented and tested. See zendoc-template#25 for the tracking issue and scope.

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.

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.