zendoc 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+zendoc/__init__.py,sha256=dzzQyw5WajnTEbrH2wyK4e4rXtpngpM95xqwgg3khNA,549
+zendoc/headings.py,sha256=do5GimUOf5fLAoYL3B26BOaPH5vLG7t8Tz39v1I27Pk,4911
+zendoc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zendoc/refs.py,sha256=Ad6clNFnU0_tWNC8-ixfQ196Xj3471Pnbf5Sr_C1uwY,5650
+zendoc/util.py,sha256=WNrbKomO3gh5khiwpWd0t0XGV0CE5i5DHZDGgYj_2EI,2169
+zendoc-0.1.0.dist-info/METADATA,sha256=t1vwqp-iGcInDcBMhiT_IgHt_07JT0moZVl-PRbPkqE,2941
+zendoc-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+zendoc-0.1.0.dist-info/entry_points.txt,sha256=cyid0A-qxc432LeM9dCznLYDYf1ldgswCpbDEt_2ShY,114
+zendoc-0.1.0.dist-info/licenses/LICENSE,sha256=qk54ayQf53MkX-HvpfOn2dFrvVVImmpvdYaKjPv2B-U,1087
+zendoc-0.1.0.dist-info/RECORD,,

zendoc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zendoc-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[markdown.extensions]
+zendoc.headings = zendoc.headings:HeadingsExtension
+zendoc.refs = zendoc.refs:RefsExtension

zendoc-0.1.0.dist-info/licenses/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.