Markdown formatting for docs and skill prose

Status: open/active

Summary

Markdown in scope follows one settled formatting rule set — ATX headings, - bullets, explicit numbering, wikilinks for entities, language-tagged fences, hand-formatted tables, quoted-schema_version frontmatter, no raw HTML, prose wrapped at 100 — chosen for Obsidian-first authoring in D-0008-markdown-standard.

Rule

Every markdown file under the scoped paths conforms to the rule set decided in D-0008-markdown-standard:

Axis	Rule
Headings	ATX (`#`…`######`); exactly one H1, matching the frontmatter `title`. No Setext.
Line length	Wrap prose at 100 columns. Tables, fenced code, headings, link targets, and frontmatter are exempt — never reflow them.
Unordered lists	`-` only.
Ordered lists	Explicit numbering (`1.` `2.` `3.`), not lazy (`1.` `1.` `1.`).
Links	Inline (`[text](url)`) for external URLs; wikilinks (`…`) for catalogued entities. No reference-style links.
Block-ids	Line-terminal `^anchor` at the end of the tagged block.
Transclusion	`file` / `file`; never a pasted copy.
Code fences	Triple-backtick with a language tag; no indented code blocks.
Tables	Hand-formatted; not reflowed and not width-limited by any tool.
Frontmatter	YAML between `---` fences; `schema_version` quoted; block-list style for `tags` / `related` / `applies_to.paths`. The entity schema is authoritative on shapes.
HTML	No raw HTML elements. `<…>` placeholder notation and angle brackets inside code/wikilinks are not HTML and are allowed.
Trailing whitespace	Stripped.
Final newline	Exactly one trailing `\n`.
Wikilink rename safety	Per D-0002-entity-identifier-shape — the id is the stable anchor; the slug never tracks title changes.

The rule set also inherits three authoring rules from docs/CLAUDE.md and may not soften them:

Be Succinct — succinct but fully explanatory prose; avoid modifiers that add nothing.
Use Structure — prefer a table over a free-form list for parallel-shape content.
Naming — refer to the project as SDLC (uppercase).

Why

The corpus drifts on formatting, costing per-PR re-litigation and tripping Obsidian (block-ids, frontmatter, table reflow). A settled rule set lets a reviewer cite instead of re-argue, and gives the future formatter (T-0007/T-0008) an unambiguous target. The full rationale, per-axis tradeoffs, and Obsidian-compatibility analysis live in D-0008-markdown-standard.

How to apply

Enforcement is split three ways; honor the right track per rule:

Track	Rules	How
Formatter	List markers, ordered-list explicitness, code-fence form, trailing whitespace, final newline, prose line-length (tables/code/headings exempt)	rumdl (D-0011-markdown-formatting-tool), configured by `.rumdl.toml` at the repo root. Runs on every commit via the `markdown-fmt` lefthook step and on demand via `/markdown-format` or `just fmt-markdown`. `rumdl check docs solutions/ontological` gates the corpus in `sdlc.yaml`.
Schema validator	Frontmatter shapes (`schema_version` quoting, list styles), id/filename shape	`sdlc entities validate` (`solutions/ontological/lib/model/ops/validate.ts`) and the identifier audit (`sdlc entities check-identifiers`) — already live; the markdown formatter does not own these.
Reviewer (subjective)	Be Succinct, Use Structure, SDLC-uppercase naming, HTML prohibition, wikilink-vs-inline choice	Human review. A spell-check target may assist with SDLC casing; the judgment stays with the reviewer.

The formatter is rumdl, chosen in D-0011-markdown-formatting-tool and wired in by T-0008 (the markdown-fmt lefthook step, the fmt-markdown / check-markdown justfile recipes, the /markdown-format skill, the sdlc.yaml rumdl check gate, and the one-time corpus reformat). The rule set lives in .rumdl.toml; bumps to the pinned rumdl@0.2.9 are gated by the sdlc gate markdown-fixtures regression fixtures. This Standard is open/active: the formatter mechanically enforces the Formatter-track rules on every commit. Two residual classes stay deferred per D-0011-markdown-formatting-tool and are disabled with a note in .rumdl.toml — broken relative links (MD057/MD051/MD052) await a link-repair follow-up, and a handful of over-long lines whose length is one unbreakable inline-code span are carved out per file.

Anti-examples

Setext heading — Title underlined with ==== instead of # Title. Violates the ATX-only rule; breaks reliable Obsidian heading transclusion for H3+ siblings.
Lazy ordered list — 1. 1. 1. for three steps. Violates the explicit-numbering rule; renders inconsistently in source view.
Reflowed table — a tool rewraps a table so every row fits 100 columns, exploding the diff. Violates the tables rule (hand-formatted, never reflowed) and the line-length exemption.
Raw HTML — <br> or <details> in a docs/ file. Violates the HTML prohibition. (<basename> in prose or Record<string> in a code span is not a violation — those are placeholder/code notation.)
Reference-style link — [text][ref] with a [ref]: url footnote for an external URL. Violates the link-style rule; use an inline link.

Notes

Decided in D-0008-markdown-standard; this Standard is the enforceable codification.
Tool choice: T-0007 / D-0011-markdown-formatting-tool (rumdl). Implementation and one-time reformat: T-0008.
Broken-link checking (MD057/MD051/MD052) is available in rumdl’s check but stays disabled-with-note in .rumdl.toml pending a link-repair follow-up — see D-0011-markdown-formatting-tool → Open questions.

← Back to Standards