zendoc 0.1.0

A family of Python-Markdown extensions for section cross-references and bibliography/citation handling

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. Factored out of zendoc-template so it can be installed and reused independently of that template.

Status: early - zendoc.headings and zendoc.refs are implemented; citation handling isn't yet. 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.

import markdown

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

# Introduction {: #intro }

See \ref{intro} for background.

\ref{intro} resolves to a link reading 1 - the heading's current section number - and stays correct if sections are reordered, since numbering is recomputed 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

To build the documentation locally:

pip install -e ".[docs]"
zensical serve

License

MIT - see LICENSE.