zendoc 0.1.0__tar.gz

zendoc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest --cov=zendoc
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pip install -e ".[docs]"
+      - run: zensical build --clean --strict

zendoc-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pip install -e ".[docs]"
+      - run: zensical build --clean --strict
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

zendoc-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

zendoc-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+site/

zendoc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Buckwell and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zendoc-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: zendoc
+Version: 0.1.0
+Summary: A family of Python-Markdown extensions for section cross-references and bibliography/citation handling
+Project-URL: Homepage, https://github.com/buckwem/zendoc-extension
+Project-URL: Issues, https://github.com/buckwem/zendoc-extension/issues
+Author: Mark Buckwell
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: markdown>=3.4
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-markdown; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: zensical; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# zendoc
+
+A family of [Python-Markdown](https://python-markdown.github.io/) extensions
+for section cross-references and bibliography/citation handling, in the
+spirit of [pymdown-extensions](https://facelessuser.github.io/pymdown-extensions/):
+each extension is independent and enabled separately. Factored out of
+[zendoc-template](https://github.com/buckwem/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](https://github.com/buckwem/zendoc-template/issues/25)
+> for the tracking issue and scope.
+
+**[Full documentation](https://buckwem.github.io/zendoc-extension/)**
+
+## Installation
+
+```bash
+pip install zendoc
+```
+
+## Extensions
+
+| Extension | Description |
+|---|---|
+| [`zendoc.headings`](https://buckwem.github.io/zendoc-extension/extensions/headings/) | Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...). |
+| [`zendoc.refs`](https://buckwem.github.io/zendoc-extension/extensions/refs/) | `\ref{id}` section cross-references, resolving to the target's current number - similar in spirit to LaTeX's `\ref`. |
+
+```python
+import markdown
+
+html = markdown.markdown(text, extensions=["zendoc.headings", "zendoc.refs"])
+```
+
+```md
+# 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](https://buckwem.github.io/zendoc-extension/) for options, multi-page
+registry sharing, and full syntax details.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+To build the documentation locally:
+
+```bash
+pip install -e ".[docs]"
+zensical serve
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE).

zendoc-0.1.0/README.md

@@ -0,0 +1,66 @@
+# zendoc
+
+A family of [Python-Markdown](https://python-markdown.github.io/) extensions
+for section cross-references and bibliography/citation handling, in the
+spirit of [pymdown-extensions](https://facelessuser.github.io/pymdown-extensions/):
+each extension is independent and enabled separately. Factored out of
+[zendoc-template](https://github.com/buckwem/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](https://github.com/buckwem/zendoc-template/issues/25)
+> for the tracking issue and scope.
+
+**[Full documentation](https://buckwem.github.io/zendoc-extension/)**
+
+## Installation
+
+```bash
+pip install zendoc
+```
+
+## Extensions
+
+| Extension | Description |
+|---|---|
+| [`zendoc.headings`](https://buckwem.github.io/zendoc-extension/extensions/headings/) | Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...). |
+| [`zendoc.refs`](https://buckwem.github.io/zendoc-extension/extensions/refs/) | `\ref{id}` section cross-references, resolving to the target's current number - similar in spirit to LaTeX's `\ref`. |
+
+```python
+import markdown
+
+html = markdown.markdown(text, extensions=["zendoc.headings", "zendoc.refs"])
+```
+
+```md
+# 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](https://buckwem.github.io/zendoc-extension/) for options, multi-page
+registry sharing, and full syntax details.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+To build the documentation locally:
+
+```bash
+pip install -e ".[docs]"
+zensical serve
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE).

zendoc-0.1.0/docs/about/changelog.md

@@ -0,0 +1,13 @@
+# Release Notes
+
+## 0.1.0 (2026-07-14)
+
+Initial release.
+
+- `zendoc.headings`: heading ids and hierarchical section numbering,
+  backed by a shared `IdRegistry`.
+- `zendoc.refs`: `\ref{id}` section cross-references, resolving to the
+  target's current section number, including forward references within a
+  document and across a shared registry.
+- Documentation site built with Zensical, published at
+  [buckwem.github.io/zendoc-extension](https://buckwem.github.io/zendoc-extension/).

zendoc-0.1.0/docs/about/license.md

@@ -0,0 +1,5 @@
+# License
+
+```text
+--8<-- "LICENSE"
+```

zendoc-0.1.0/docs/extensions/headings.md

@@ -0,0 +1,104 @@
+# Headings
+
+## Overview
+
+`zendoc.headings` gives every heading in a document an `id` and a
+hierarchical section number, and records both - along with the heading's
+text and level - in a shared registry keyed by a document "source" name.
+
+It exists to be a foundation other zendoc extensions build on:
+[zendoc.refs](refs.md) resolves `\ref{id}` by looking an id up in exactly
+this registry. You can also enable `zendoc.headings` on its own if you just
+want ids/numbers on your headings without cross-references.
+
+Numbering is per-document and hierarchical: an `h1` is a top-level counter
+("1", "2", ...), an `h2` nests under the nearest preceding `h1` ("1.1",
+"1.2", ...), and so on down through `h6`. Numbers are recomputed from
+scratch on every conversion, so reordering headings always produces correct
+numbers on the next build - there's no stored/stale numbering state.
+
+## Example
+
+```md
+# Introduction
+
+## Background
+
+## Scope
+
+# Method
+```
+
+produces (numbers shown for illustration - `zendoc.headings` doesn't render
+numbers into the heading text itself, only into the registry; see
+[zendoc.refs](refs.md) for rendering a number inline):
+
+| Heading | id | number |
+|---|---|---|
+| Introduction | `introduction` | `1` |
+| Background | `background` | `1.1` |
+| Scope | `scope` | `1.2` |
+| Method | `method` | `2` |
+
+## Ids
+
+An id comes from one of, in order of precedence:
+
+1. An explicit id set via
+   [`attr_list`](https://python-markdown.github.io/extensions/attr_list/),
+   e.g. `# Introduction {: #custom-id }`.
+2. Python-Markdown's own [`toc`](https://python-markdown.github.io/extensions/toc/)
+   extension, which `zendoc.headings` enables automatically (with its
+   defaults) if you haven't already enabled it yourself - so if you *have*
+   configured `toc` (e.g. with `permalink: true`), that configuration is
+   left untouched and reused.
+3. A minimal built-in slugify fallback, used only if `toc` is somehow not
+   registered at all (this should not normally happen, since
+   `zendoc.headings` enables it).
+
+## Unnumbered headings
+
+A heading with an `unnumbered` class - e.g. a cover page or title slide -
+still gets an id, but is skipped when computing section numbers, so it
+doesn't consume a counter position:
+
+```md
+# Cover Page {: .unnumbered }
+
+# Introduction
+```
+
+`Introduction` above is still numbered `1`, as if `Cover Page` weren't
+there at all.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `source` | `str` | `""` | Identifier for the current document (e.g. its file path). Used to scope this document's entries in the registry, and to safely clear/replace them on a rebuild of the same document. |
+| `registry` | `IdRegistry \| None` | a new `IdRegistry()` | Share one registry across multiple documents/conversions - see below. Passed as a constructor keyword, not a string-based config value (Python-Markdown's config system can't carry arbitrary Python objects safely). |
+
+## Sharing a registry across a multi-page build
+
+To resolve cross-page references, every page in a build needs to write into
+- and read from - the *same* `IdRegistry` instance. Construct one and pass
+it to every page's extension instance, along with that page's own `source`:
+
+```python
+import markdown
+from zendoc.headings import HeadingsExtension
+from zendoc.util import IdRegistry
+
+registry = IdRegistry()
+
+for path, text in pages:
+    html = markdown.markdown(
+        text,
+        extensions=[HeadingsExtension(registry=registry, source=path)],
+    )
+```
+
+A duplicate id registered from two *different* sources raises
+`zendoc.util.DuplicateIdError` - re-converting the *same* source (e.g. a
+live-reload dev server) is safe and expected; its previous entries are
+cleared first.

zendoc-0.1.0/docs/extensions/refs.md

@@ -0,0 +1,125 @@
+# Refs
+
+## Overview
+
+`zendoc.refs` adds a `\ref{id}` cross-reference syntax - similar in spirit
+to LaTeX's `\ref` - that resolves to the *current* section number of the
+heading with that id:
+
+```md
+# Introduction {: #intro }
+
+See \ref{intro} for background.
+```
+
+renders `\ref{intro}` as a link to `#intro` reading `1`. Because the number
+is looked up fresh on every conversion (see [zendoc.headings](headings.md)),
+it stays correct even if sections are added, removed, or reordered - you
+never have to manually renumber a cross-reference.
+
+`zendoc.refs` depends on the id/number registry that
+[zendoc.headings](headings.md) builds. If you enable `zendoc.refs` on its
+own, it transparently enables `zendoc.headings` for you with matching
+defaults, so a single document works with no extra configuration. If you
+list both explicitly, list `zendoc.headings` first - see
+[Multi-page builds](#multi-page-builds) below.
+
+## Syntax
+
+```
+\ref{<id>}
+```
+
+`<id>` is the target heading's id - either one you set explicitly via
+[`attr_list`](https://python-markdown.github.io/extensions/attr_list/)
+(`# Introduction {: #intro }`), or the one
+[`toc`](https://python-markdown.github.io/extensions/toc/) derived
+automatically from the heading text (see [zendoc.headings](headings.md#ids)
+for the exact precedence).
+
+`\ref{...}` is recognised the same way Python-Markdown's own inline syntax
+is - meaning it's protected inside inline code spans and fenced code
+blocks, so it's safe to show as a literal example:
+
+````md
+Type `\ref{intro}` to reference a section.
+
+```
+\ref{intro}
+```
+````
+
+Neither of the two shown above is resolved; both render the literal text.
+
+## Forward references
+
+A reference to a heading defined *later* in the same document resolves
+correctly:
+
+```md
+See \ref{background} below.
+
+## Background {: #background }
+```
+
+## Unresolved references
+
+`\ref{id}` renders the `unresolved` marker (`??` by default) instead of a
+number when:
+
+- `id` doesn't exist in the registry at all - e.g. a typo, or a reference
+  to a heading in a page that hasn't been converted yet in a multi-page
+  build (the same way an undefined LaTeX `\ref` shows `??` until a later
+  compilation pass).
+- `id` exists but belongs to a heading marked `unnumbered` (see
+  [zendoc.headings](headings.md#unnumbered-headings)) - it's still a valid
+  link target in this case, just without a number to show.
+
+```md
+# Cover Page {: .unnumbered }
+
+See \ref{cover-page}.
+```
+
+renders `\ref{cover-page}` as `??`, linked to `#cover-page`.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `unresolved` | `str` | `"??"` | Text rendered when `id` doesn't resolve to a numbered heading. |
+| `registry` | `IdRegistry \| None` | discovered from a sibling `zendoc.headings`, or a new one | Share one registry across multiple documents - see below. Passed as a constructor keyword, not a string-based config value. |
+
+## Multi-page builds
+
+To resolve cross-page references, give `zendoc.headings` and `zendoc.refs`
+the *same* `IdRegistry` on every page, converting pages in the order
+cross-references should become resolvable in (a reference to a page not
+yet converted resolves to `unresolved`, as above):
+
+```python
+import markdown
+from zendoc.headings import HeadingsExtension
+from zendoc.refs import RefsExtension
+from zendoc.util import IdRegistry
+
+registry = IdRegistry()
+
+for path, text in pages:
+    html = markdown.markdown(
+        text,
+        extensions=[
+            HeadingsExtension(registry=registry, source=path),
+            RefsExtension(registry=registry),
+        ],
+    )
+```
+
+If you enable both extensions by name instead (e.g. from a
+`mkdocs.yml`/`zensical.toml`-style config, where you can't pass a shared
+`IdRegistry` object directly), list `zendoc.headings` before `zendoc.refs`:
+`zendoc.refs` looks for an already-registered `zendoc.headings` instance on
+the current `Markdown` object and reuses its registry automatically, so a
+per-page site-generator integration (a plugin owning one shared registry
+across the whole build) is the way to get cross-page resolution without
+constructing extension instances by hand.

zendoc-0.1.0/docs/index.md

@@ -0,0 +1,51 @@
+# zendoc
+
+zendoc is a family of [Python-Markdown](https://python-markdown.github.io/)
+extensions for section cross-references and bibliography/citation handling,
+in the spirit of [pymdown-extensions](https://facelessuser.github.io/pymdown-extensions/):
+each extension is independent and enabled separately, so you only pay for
+what you use.
+
+zendoc was factored out of
+[zendoc-template](https://github.com/buckwem/zendoc-template) so it can be
+installed and reused independently of that template - see
+[zendoc-template#25](https://github.com/buckwem/zendoc-template/issues/25)
+for the tracking issue and original motivation.
+
+## Extensions
+
+| Extension | Description |
+|---|---|
+| [zendoc.headings](extensions/headings.md) | Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...). |
+| [zendoc.refs](extensions/refs.md) | `\ref{id}` section cross-references, resolving to the target's current number - similar in spirit to LaTeX's `\ref`. |
+
+Bibliography/citation handling is planned but not implemented yet.
+
+## Quick example
+
+```python
+import markdown
+
+html = markdown.markdown(
+    """
+# Introduction
+
+See \\ref{background} for context.
+
+## Background
+
+...
+""",
+    extensions=["zendoc.headings", "zendoc.refs"],
+)
+```
+
+`\ref{background}` resolves to `1.1` - the current section number of the
+heading it points to - and stays correct if headings are reordered, because
+numbering is recomputed fresh on every conversion.
+
+## Status
+
+Early. `zendoc.headings` and `zendoc.refs` are implemented and tested;
+citation-key management is not yet built. See the
+[Release Notes](about/changelog.md) for what's landed so far.

zendoc-0.1.0/docs/installation.md

@@ -0,0 +1,60 @@
+# Installation
+
+## From PyPI
+
+```bash
+pip install zendoc
+```
+
+`zendoc` depends only on [`Markdown`](https://python-markdown.github.io/)
+(>= 3.4) - no other runtime dependencies.
+
+## Enabling an extension
+
+Each zendoc 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:
+
+```python
+import markdown
+
+html = markdown.markdown(text, extensions=["zendoc.headings", "zendoc.refs"])
+```
+
+Or in a `mkdocs.yml`/`zensical.toml`-style config:
+
+```yaml
+markdown_extensions:
+  - zendoc.headings
+  - zendoc.refs
+```
+
+```toml
+[project.markdown_extensions.zendoc.headings]
+[project.markdown_extensions.zendoc.refs]
+```
+
+See each extension's own page for its options and for how to share one
+registry across multiple pages of a site build:
+
+- [zendoc.headings](extensions/headings.md)
+- [zendoc.refs](extensions/refs.md)
+
+## Development install
+
+```bash
+git clone https://github.com/buckwem/zendoc-extension
+cd zendoc-extension
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+To build these docs locally:
+
+```bash
+pip install -e ".[docs]"
+zensical serve
+```

zendoc-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zendoc"
+version = "0.1.0"
+description = "A family of Python-Markdown extensions for section cross-references and bibliography/citation handling"
+readme = "README.md"
+license = "MIT"
+authors = [
+  { name = "Mark Buckwell" },
+]
+requires-python = ">=3.10"
+dependencies = [
+  "Markdown>=3.4",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Text Processing :: Markup :: Markdown",
+]
+
+[project.urls]
+Homepage = "https://github.com/buckwem/zendoc-extension"
+Issues = "https://github.com/buckwem/zendoc-extension/issues"
+
+[project.entry-points."markdown.extensions"]
+"zendoc.headings" = "zendoc.headings:HeadingsExtension"
+"zendoc.refs" = "zendoc.refs:RefsExtension"
+
+[project.optional-dependencies]
+dev = [
+  "ruff",
+  "mypy",
+  "types-Markdown",
+  "pytest",
+  "pytest-cov",
+]
+docs = [
+  "zensical",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zendoc"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

zendoc-0.1.0/src/zendoc/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+"""zendoc: a family of independent Python-Markdown extensions for section
+cross-references and bibliography/citation handling, in the spirit of
+pymdown-extensions - each is its own extension, enabled separately:
+
+- ``zendoc.headings`` - heading ids and hierarchical section numbers.
+- ``zendoc.refs`` - ``\\ref{id}`` section cross-references.
+
+See https://github.com/buckwem/zendoc-extension for documentation.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

zendoc-0.1.0/src/zendoc/headings.py

@@ -0,0 +1,127 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+"""zendoc.headings: gives every heading an id and a hierarchical section
+number, recorded in a shared :class:`~zendoc.util.IdRegistry` that other
+zendoc extensions (currently :mod:`zendoc.refs`) look entries up in.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as etree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.extensions.toc import TocExtension
+from markdown.treeprocessors import Treeprocessor
+
+from zendoc.util import IdRegistry
+
+HEADING_TAGS = {"h1", "h2", "h3", "h4", "h5", "h6"}
+
+
+def _slugify(text: str) -> str:
+    """Minimal fallback slug, used only when 'toc' hasn't already assigned an
+    id. Enable Python-Markdown's own 'toc' extension for slugs that match the
+    rest of a 'toc'-rendered document exactly (unicode handling, custom
+    separators, etc.) - this fallback exists only so the registry still works
+    if a caller genuinely doesn't want a table of contents.
+    """
+    slug = re.sub(r"[^\w\s-]", "", text).strip().lower()
+    return re.sub(r"\s+", "-", slug)
+
+
+class HeadingsTreeprocessor(Treeprocessor):
+    """Records every h1-h6 element's id, and its hierarchical section number,
+    in a shared :class:`IdRegistry`, keyed by the current document's source
+    name.
+
+    Numbering is per-document: h1 is a top-level counter, h2 nests under the
+    nearest preceding h1 ("1.1", "1.2", ...), and so on through h6 - reset
+    from scratch on every call, so reordering headings within a document
+    always produces correct numbers on the next build. A heading with an
+    ``unnumbered`` class (e.g. via ``# Title {: .unnumbered }``) is still
+    given an id but excluded from numbering - its counter position is
+    skipped entirely - so its registered ``number`` is ``None``.
+
+    Runs at a lower priority than 'toc' (registered at 5) so it always reads
+    the final id 'toc' assigned - including one already set explicitly via
+    'attr_list' - rather than racing it.
+    """
+
+    def __init__(self, md: Markdown, registry: IdRegistry, source: str) -> None:
+        super().__init__(md)
+        self.registry = registry
+        self.source = source
+
+    def run(self, root: etree.Element) -> None:
+        self.registry.clear_source(self.source)
+        counters = [0] * 6
+        for el in root.iter():
+            if el.tag not in HEADING_TAGS:
+                continue
+            text = "".join(el.itertext())
+            heading_id = el.get("id")
+            if not heading_id:
+                heading_id = _slugify(text)
+                el.set("id", heading_id)
+
+            level = int(el.tag[1])
+            classes = (el.get("class") or "").split()
+            if "unnumbered" in classes:
+                number = None
+            else:
+                counters[level - 1] += 1
+                for deeper in range(level, 6):
+                    counters[deeper] = 0
+                number = ".".join(str(c) for c in counters[:level])
+
+            self.registry.register(
+                source=self.source,
+                id=heading_id,
+                level=level,
+                text=text,
+                number=number,
+            )
+
+
+class HeadingsExtension(Extension):
+    """Python-Markdown extension assigning ids and section numbers to headings."""
+
+    def __init__(self, **kwargs: object) -> None:
+        # Popped rather than run through Extension's own config/setConfig:
+        # that machinery bool-coerces any config value whose *current*
+        # default is None (see markdown.util.parseBoolValue), which would
+        # silently corrupt a real IdRegistry object passed in explicitly.
+        registry = kwargs.pop("registry", None)
+        self.registry: IdRegistry = (
+            registry if isinstance(registry, IdRegistry) else IdRegistry()
+        )
+        self.config = {
+            "source": [
+                "",
+                "Identifier for the current document (e.g. its path), used "
+                "to scope this document's own entries in the registry.",
+            ],
+        }
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        md.registerExtension(self)
+        # Heading ids are 'toc''s job (including respecting one 'attr_list'
+        # already set) - reuse it rather than re-deriving slugs here, but
+        # don't clobber a caller's own 'toc' config (e.g. permalink=True) if
+        # they've already enabled it themselves.
+        if "toc" not in md.treeprocessors:
+            TocExtension().extendMarkdown(md)
+        source: str = self.getConfig("source")
+        md.treeprocessors.register(
+            HeadingsTreeprocessor(md, self.registry, source),
+            "zendoc-headings",
+            4,
+        )
+
+
+def makeExtension(**kwargs: object) -> HeadingsExtension:
+    return HeadingsExtension(**kwargs)

zendoc-0.1.0/src/zendoc/refs.py

@@ -0,0 +1,138 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+"""zendoc.refs: ``\\ref{id}`` section cross-reference syntax, resolving to
+the referenced heading's current section number - similar in spirit to
+LaTeX's ``\\ref``. Builds on the id registry from :mod:`zendoc.headings`,
+which is auto-enabled with matching defaults if not already present.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as etree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.inlinepatterns import InlineProcessor
+from markdown.treeprocessors import Treeprocessor
+
+from zendoc.headings import HeadingsExtension
+from zendoc.util import IdRegistry
+
+REF_RE = r"\\ref\{([^}\s]+)\}"
+
+
+class RefInlineProcessor(InlineProcessor):
+    """Matches ``\\ref{id}`` and emits an unresolved placeholder ``<a>``
+    carrying the referenced id in a ``data-zendoc-ref`` attribute.
+
+    Registered at a low inline-pattern priority so it runs after 'backtick'
+    (190) and 'escape' (180) - meaning inline code spans are already stashed
+    out of reach by the time this pattern runs, so ``\\ref{...}`` shown as
+    literal example syntax inside `` `code` `` survives untouched, the same
+    protection fenced code blocks already get from being stashed even
+    earlier, during preprocessing.
+
+    The placeholder can't be resolved to a real section number here: inline
+    patterns run before the current document's own headings have been
+    numbered (see HeadingsTreeprocessor, priority 4, which runs after this
+    pattern's containing 'inline' treeprocessor, priority 20) - resolution
+    happens later, in RefResolverTreeprocessor.
+    """
+
+    def handleMatch(  # type: ignore[override]
+        self, m: re.Match[str], data: str
+    ) -> tuple[etree.Element, int, int]:
+        el = etree.Element("a")
+        el.set("data-zendoc-ref", m.group(1))
+        el.set("class", "zendoc-ref")
+        return el, m.start(0), m.end(0)
+
+
+class RefResolverTreeprocessor(Treeprocessor):
+    """Resolves the placeholder ``<a data-zendoc-ref="id">`` elements left by
+    :class:`RefInlineProcessor` to the referenced heading's section number,
+    once the current document's own headings have been numbered.
+
+    Runs at a lower priority than 'zendoc-headings' (4) so every heading in
+    *this* document - including one defined further down the page than
+    where it's referenced - is already registered by the time resolution
+    happens. A reference to a heading in a document not yet processed in
+    this build (e.g. a later page in a multi-page site) can't be resolved
+    yet either; both cases fall back to `unresolved`, the same way an
+    undefined LaTeX \\ref shows "??" until a later compilation pass.
+    """
+
+    def __init__(self, md: Markdown, registry: IdRegistry, unresolved: str = "??") -> None:
+        super().__init__(md)
+        self.registry = registry
+        self.unresolved = unresolved
+
+    def run(self, root: etree.Element) -> None:
+        for el in root.iter("a"):
+            ref_id = el.get("data-zendoc-ref")
+            if ref_id is None:
+                continue
+            del el.attrib["data-zendoc-ref"]
+            record = self.registry.get(ref_id)
+            if record is None or record.number is None:
+                el.text = self.unresolved
+                el.set("class", "zendoc-ref zendoc-ref-unresolved")
+                if record is not None:
+                    # Known heading, just unnumbered (e.g. {: .unnumbered }) -
+                    # still a valid link target, unlike a genuinely unknown id.
+                    el.set("href", f"#{ref_id}")
+            else:
+                el.text = record.number
+                el.set("href", f"#{ref_id}")
+
+
+class RefsExtension(Extension):
+    """Python-Markdown extension providing the ``\\ref{id}`` syntax."""
+
+    def __init__(self, **kwargs: object) -> None:
+        # See HeadingsExtension for why this is popped rather than run
+        # through Extension's own config/setConfig machinery. None here
+        # means "discover the registry from a sibling HeadingsExtension",
+        # not "use an empty registry" - that distinction can't be made once
+        # a value has round-tripped through setConfig.
+        registry = kwargs.pop("registry", None)
+        self.registry: IdRegistry | None = registry if isinstance(registry, IdRegistry) else None
+        self.config = {
+            "unresolved": [
+                "??",
+                "Text rendered by \\ref{id} when id doesn't resolve to a "
+                "numbered heading - unknown id, or a heading marked "
+                "unnumbered.",
+            ],
+        }
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        md.registerExtension(self)
+        registry = self.registry
+        if registry is None:
+            headings_ext = next(
+                (ext for ext in md.registeredExtensions if isinstance(ext, HeadingsExtension)),
+                None,
+            )
+            if headings_ext is None:
+                headings_ext = HeadingsExtension()
+                headings_ext.extendMarkdown(md)
+            registry = headings_ext.registry
+        unresolved: str = self.getConfig("unresolved")
+        md.inlinePatterns.register(
+            RefInlineProcessor(REF_RE, md),
+            "zendoc-ref",
+            45,
+        )
+        md.treeprocessors.register(
+            RefResolverTreeprocessor(md, registry, unresolved),
+            "zendoc-ref-resolver",
+            2,
+        )
+
+
+def makeExtension(**kwargs: object) -> RefsExtension:
+    return RefsExtension(**kwargs)

zendoc-0.1.0/src/zendoc/util.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+"""Shared data structures used by more than one zendoc extension.
+
+A single :class:`IdRegistry` instance is meant to be shared across every
+source document in a build (one extension instance per document, e.g. one
+:class:`~zendoc.headings.HeadingsExtension` call per page), so that
+:mod:`zendoc.refs` (and a future citation extension) can resolve an id to
+the document, heading, and current section number that defines it,
+regardless of which document is currently being converted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class HeadingRecord:
+    source: str
+    id: str
+    level: int
+    text: str
+    number: str | None = None
+
+
+class DuplicateIdError(ValueError):
+    """Raised when the same id is registered from two different sources."""
+
+
+class IdRegistry:
+    def __init__(self) -> None:
+        self._headings: dict[str, HeadingRecord] = {}
+
+    def register(
+        self, source: str, id: str, level: int, text: str, number: str | None = None
+    ) -> None:
+        existing = self._headings.get(id)
+        if existing is not None and existing.source != source:
+            raise DuplicateIdError(
+                f"heading id {id!r} is already registered from "
+                f"{existing.source!r}; cannot also register it from {source!r}"
+            )
+        self._headings[id] = HeadingRecord(
+            source=source, id=id, level=level, text=text, number=number
+        )
+
+    def get(self, id: str) -> HeadingRecord | None:
+        return self._headings.get(id)
+
+    def __contains__(self, id: str) -> bool:
+        return id in self._headings
+
+    def clear_source(self, source: str) -> None:
+        """Drops every entry previously registered from source.
+
+        Needed so re-converting the same document (e.g. a live-reload dev
+        server) can't leave a stale id behind after a heading's text - and
+        therefore its slug - changes between builds.
+        """
+        for stale_id in [k for k, v in self._headings.items() if v.source == source]:
+            del self._headings[stale_id]

zendoc-0.1.0/tests/test_headings.py

@@ -0,0 +1,104 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+import markdown
+import pytest
+
+from zendoc.headings import HeadingsExtension
+from zendoc.util import DuplicateIdError, IdRegistry
+
+
+def _convert(text: str, registry: IdRegistry, source: str) -> str:
+    md = markdown.Markdown(
+        extensions=["attr_list", HeadingsExtension(registry=registry, source=source)]
+    )
+    return md.convert(text)
+
+
+def test_heading_gets_an_id_and_is_registered() -> None:
+    registry = IdRegistry()
+    html = _convert("# Introduction\n", registry, "intro.md")
+    assert 'id="introduction"' in html
+    record = registry.get("introduction")
+    assert record is not None
+    assert record.source == "intro.md"
+    assert record.level == 1
+    assert record.text == "Introduction"
+    assert record.number == "1"
+
+
+def test_nested_headings_get_hierarchical_numbers() -> None:
+    registry = IdRegistry()
+    _convert("# Chapter\n\n## Setup\n\n## Usage\n\n# Next Chapter\n", registry, "doc.md")
+    assert registry.get("chapter").number == "1"  # type: ignore[union-attr]
+    assert registry.get("setup").number == "1.1"  # type: ignore[union-attr]
+    assert registry.get("usage").number == "1.2"  # type: ignore[union-attr]
+    assert registry.get("next-chapter").number == "2"  # type: ignore[union-attr]
+
+
+def test_unnumbered_heading_has_no_number_but_gets_an_id() -> None:
+    registry = IdRegistry()
+    _convert("# Cover Page {: .unnumbered }\n\n# Introduction\n", registry, "doc.md")
+    assert registry.get("cover-page").number is None  # type: ignore[union-attr]
+    # unnumbered heading doesn't consume a counter slot
+    assert registry.get("introduction").number == "1"  # type: ignore[union-attr]
+
+
+def test_explicit_id_is_respected() -> None:
+    registry = IdRegistry()
+    _convert("# Introduction {: #custom-id }\n", registry, "intro.md")
+    assert registry.get("custom-id") is not None
+    assert registry.get("introduction") is None
+
+
+def test_shared_registry_across_sources() -> None:
+    registry = IdRegistry()
+    _convert("# Introduction\n", registry, "intro.md")
+    _convert("# Setup\n", registry, "setup.md")
+    assert registry.get("introduction").source == "intro.md"  # type: ignore[union-attr]
+    assert registry.get("setup").source == "setup.md"  # type: ignore[union-attr]
+
+
+def test_duplicate_id_across_sources_raises() -> None:
+    registry = IdRegistry()
+    _convert("# Introduction\n", registry, "intro.md")
+    with pytest.raises(DuplicateIdError):
+        _convert("# Introduction\n", registry, "other.md")
+
+
+def test_rebuilding_same_source_does_not_raise() -> None:
+    registry = IdRegistry()
+    _convert("# Introduction\n", registry, "intro.md")
+    _convert("# Introduction\n", registry, "intro.md")
+    assert registry.get("introduction").source == "intro.md"  # type: ignore[union-attr]
+
+
+def test_stale_heading_cleared_on_rebuild() -> None:
+    registry = IdRegistry()
+    _convert("# Old Title\n", registry, "intro.md")
+    _convert("# New Title\n", registry, "intro.md")
+    assert registry.get("old-title") is None
+    new_title = registry.get("new-title")
+    assert new_title is not None
+    assert new_title.source == "intro.md"
+
+
+def test_reuses_callers_own_toc_config() -> None:
+    registry = IdRegistry()
+    md = markdown.Markdown(
+        extensions=[
+            "toc",
+            HeadingsExtension(registry=registry, source="intro.md"),
+        ],
+        extension_configs={"toc": {"permalink": True}},
+    )
+    html = md.convert("# Introduction\n")
+    assert "headerlink" in html
+    assert registry.get("introduction") is not None
+
+
+def test_entry_point_name_resolves() -> None:
+    md = markdown.Markdown(extensions=["zendoc.headings"])
+    assert md.convert("# Introduction\n") == (
+        '<h1 id="introduction">Introduction</h1>'
+    )

zendoc-0.1.0/tests/test_refs.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+import markdown
+
+from zendoc.headings import HeadingsExtension
+from zendoc.refs import RefsExtension
+from zendoc.util import IdRegistry
+
+
+def _convert(text: str, source: str = "doc.md") -> str:
+    """Standalone use: zendoc.refs alone, auto-enabling zendoc.headings."""
+    md = markdown.Markdown(extensions=["attr_list", RefsExtension()])
+    return md.convert(text)
+
+
+def test_ref_resolves_to_section_number() -> None:
+    html = _convert("# Introduction\n\nSee \\ref{introduction}.\n")
+    assert '<a class="zendoc-ref" href="#introduction">1</a>' in html
+
+
+def test_ref_resolves_nested_heading_number() -> None:
+    html = _convert(
+        "# Chapter\n\n## Setup\n\nSee \\ref{setup}.\n\n## Usage\n\nSee \\ref{usage}.\n"
+    )
+    assert '<a class="zendoc-ref" href="#setup">1.1</a>' in html
+    assert '<a class="zendoc-ref" href="#usage">1.2</a>' in html
+
+
+def test_forward_reference_within_same_document_resolves() -> None:
+    html = _convert("See \\ref{introduction} below.\n\n# Introduction\n")
+    assert '<a class="zendoc-ref" href="#introduction">1</a>' in html
+
+
+def test_unknown_id_is_unresolved() -> None:
+    html = _convert("See \\ref{does-not-exist}.\n")
+    assert '<a class="zendoc-ref zendoc-ref-unresolved">??</a>' in html
+
+
+def test_unnumbered_heading_is_unresolved_but_linkable() -> None:
+    html = _convert("# Cover Page {: .unnumbered }\n\nSee \\ref{cover-page}.\n")
+    assert '<a class="zendoc-ref zendoc-ref-unresolved" href="#cover-page">??</a>' in html
+
+
+def test_custom_unresolved_marker() -> None:
+    md = markdown.Markdown(extensions=[RefsExtension(unresolved="[MISSING]")])
+    html = md.convert("See \\ref{nope}.\n")
+    assert ">[MISSING]</a>" in html
+
+
+def test_ref_inside_code_span_is_not_resolved() -> None:
+    html = _convert("# Introduction\n\nType `\\ref{introduction}` literally.\n")
+    assert "\\ref{introduction}" in html
+    assert "zendoc-ref" not in html
+
+
+def test_ref_inside_fenced_code_block_is_not_resolved() -> None:
+    html = _convert("# Introduction\n\n```\n\\ref{introduction}\n```\n")
+    assert "\\ref{introduction}" in html
+    assert "zendoc-ref" not in html
+
+
+def test_shares_registry_with_explicitly_enabled_headings_extension() -> None:
+    """zendoc.headings listed first, zendoc.refs second - the recommended
+    multi-page pattern: both share one registry across separate conversions."""
+    registry = IdRegistry()
+    md_page1 = markdown.Markdown(
+        extensions=[
+            HeadingsExtension(registry=registry, source="intro.md"),
+            RefsExtension(registry=registry),
+        ]
+    )
+    md_page1.convert("# Introduction\n")
+
+    md_page2 = markdown.Markdown(
+        extensions=[
+            HeadingsExtension(registry=registry, source="usage.md"),
+            RefsExtension(registry=registry),
+        ]
+    )
+    html = md_page2.convert("See \\ref{introduction}.\n")
+    assert '<a class="zendoc-ref" href="#introduction">1</a>' in html
+
+
+def test_entry_point_names_resolve_together() -> None:
+    md = markdown.Markdown(extensions=["zendoc.headings", "zendoc.refs"])
+    html = md.convert("# Introduction\n\nSee \\ref{introduction}.\n")
+    assert '<a class="zendoc-ref" href="#introduction">1</a>' in html

zendoc-0.1.0/zensical.toml

@@ -0,0 +1,68 @@
+[project]
+site_name = "zendoc"
+site_description = "A family of Python-Markdown extensions for section cross-references and bibliography/citation handling."
+site_author = "Mark Buckwell"
+site_url = "https://buckwem.github.io/zendoc-extension/"
+
+repo_url = "https://github.com/buckwem/zendoc-extension"
+repo_name = "buckwem/zendoc-extension"
+edit_uri = "edit/main/docs/"
+
+copyright = """
+Copyright © 2026 Mark Buckwell and contributors
+"""
+
+nav = [
+  {"Home" = "index.md"},
+  {"Installation" = "installation.md"},
+  {"Extensions" = [
+    {"Headings" = "extensions/headings.md"},
+    {"Refs" = "extensions/refs.md"},
+  ]},
+  {"About" = [
+    {"Release Notes" = "about/changelog.md"},
+    {"License" = "about/license.md"},
+  ]},
+]
+
+[project.theme]
+language = "en"
+features = [
+  "content.action.edit",
+  "content.code.copy",
+  "navigation.top",
+  "navigation.tracking",
+  "navigation.instant",
+]
+
+[[project.theme.palette]]
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "https://github.com/buckwem/zendoc-extension"
+
+# ----------------------------------------------------------------------------
+# Markdown extensions used to render these docs. pymdownx.snippets is used to
+# embed LICENSE (outside docs_dir) into about/license.md.
+# ----------------------------------------------------------------------------
+[project.markdown_extensions.toc]
+permalink = true
+[project.markdown_extensions.admonition]
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions.md_in_html]
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+[project.markdown_extensions.pymdownx.inlinehilite]
+[project.markdown_extensions.pymdownx.snippets]
+base_path = ["."]
+[project.markdown_extensions.pymdownx.superfences]
+[project.markdown_extensions.pymdownx.tabbed]
+alternate_style = true