F18.4 — Markdown structure
| State | Closed |
| Parent | E18 |
| Iteration | Release 6 |
| Start Date | 2026-10-25 |
| Closed Date | 2026-10-25 |
| Predecessors | F18.1 |
| Source | Owner request, 2026-10-24 |
Stories: 1 Closed
| Story | State | Depends on |
|---|---|---|
S18.4.1 — Build MarkdownUtils |
Closed | — |
MarkdownUtils, in rn_forge.commons.text.markdown behind a markdown extra,
reads the structure of a Markdown document:
- its headings and the anchors a renderer gives them;
- its link and image targets;
- its title;
- its pipe tables, with their line positions;
- its text with fenced code removed.
A documentation checker, a notes or content application, and a generator that fills a table in a page all need these.
Context
kiln parsed Markdown with regular expressions plus Python-Markdown's toc
slugifier so anchors match MkDocs. Run against kiln's 119 pages on 2026-10-24, a
markdown-it-py token stream with the same slugifier produced the same anchors on
every page, and the links differed on four pages where the expression was wrong:
it counted a link written inside inline code and missed a link whose text
contains brackets. markdown-it-py is CommonMark-compliant, maintained and
already in commons' environment through rich, so
ADR-0001 rule 1 picks it over hand-written patterns.
Design
The feature shipped as designed. MarkdownUtils, MarkdownHeading and
MarkdownTable live in rn_forge.commons.text.markdown behind the markdown
extra, imported directly. Anchors follow Python-Markdown's toc extension,
which MkDocs uses, and the parser is markdown-it-py with CommonMark and GFM
tables. The rn-forge-commons text guide (docs/guides/text.md, Markdown)
and the API reference document them, and F18.1's commons-core-has-no-extras
contract and facade test already cover the import boundary.
S18.4.1 — Build MarkdownUtils
State: Closed
Acceptance: MarkdownUtils behaves as under Design, its tests pass, the
import contracts hold and the commons site builds strictly.
Considered and rejected
- Python-Markdown alone. Its
tocextension gives exact anchors, but it exposes no link or table structure without rendering HTML and parsing that back. - Regular expressions. They miss links in bracketed text, and find links in code; markdown-it-py is CommonMark-compliant and already installed.
- markdown-it-py's own slugifier (
mdit-py-pluginsanchors). Its anchors differ from MkDocs' for punctuation and Unicode, and checking a MkDocs site is the first use.