Skip to content

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 toc extension 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-plugins anchors). Its anchors differ from MkDocs' for punctuation and Unicode, and checking a MkDocs site is the first use.