settle the Markdown dialect, and namespace an include's footnotes
Tables, footnotes, definition lists, strikethrough and automatic heading ids. Which dialect a site is written against is permanent, so ADR-0058 names the whole set at once — including the four refused, each for a reason rather than a taste: task lists publish nothing, linkify rewrites plain text into markup that ADR-0034 forbids the engine to touch, CJK is the wrong script family for a Bengali site, and the GFM bundle is a package deal for the first two. Footnotes collided with includes, as the queue predicted but worse. An include converts its file on its own bytes (ADR-0038), so goldmark numbered its notes from one again and the page carried two id="fn:1"s — the parent's reference jumped to the fragment's note. shortcodes.FootnotePrefix stamps the file name on the nested document and hands it to goldmark's id-prefix function, so the fragment gets _method-fn:1 and the page keeps fn:1. Two things nothing tested before. The extender list ships from cmd/khosra, which no package can import, so the dialect had never been rendered through the list the binary actually uses — cmd/khosra/wire_test.go now does exactly that, including that the typographer no longer eats a table's delimiter row. And the demo carries the dialect and the footnote namespacing as cases, which caught auto heading ids changing markup in three existing assertions. The reference theme gains five lines: a rule under each table row, an indent for definitions, smaller footnotes. core 2790/2800, ext 1058/2000, 34 gates green.
This commit is contained in:
@@ -904,3 +904,25 @@ commit body, not a value in the file. The check is also weaker on a squashed or
|
||||
files move in the same commit by construction.
|
||||
Revisit if: someone wants the reconciliation *moment* recorded rather than the currency, which is a
|
||||
different fact and belongs in the arc retro log.
|
||||
|
||||
## ADR-0058 — The Markdown dialect is CommonMark plus five, named once
|
||||
Date: 2026-08-01 · Status: accepted
|
||||
Decision: tables, footnotes, definition lists, strikethrough and automatic heading ids are enabled; task
|
||||
lists, linkify, CJK line breaking and the GFM bundle are refused. The list lives in `cmd/khosra/wire.go`
|
||||
beside the features, and `content-model.md` carries the authored form. Footnote ids inside an included file
|
||||
are namespaced by that file, through `shortcodes.FootnotePrefix`.
|
||||
Why: "which Markdown dialect" is permanent — content written against it cannot be un-written — so it is
|
||||
settled in one decision rather than admitted an extension per feature. The five chosen serve what this
|
||||
engine is for: footnotes carry citations in technical writing and asides in fiction, tables carry
|
||||
specifications, definition lists carry glossaries, heading ids are the half of a table of contents only the
|
||||
engine can supply. The four refused each fail a test rather than a taste: task lists publish nothing,
|
||||
linkify rewrites an author's plain text into markup that ADR-0034 says the engine may not touch, CJK is the
|
||||
wrong script family for a Bengali site, and the bundle is a package deal for two of them. All five are
|
||||
parse-phase, composing in goldmark's extender list, so the render-transform counter stays where it is.
|
||||
Consequence: cheap — five lines where features are enabled, and a test beside the list that renders the
|
||||
whole dialect through the shipped `extenders`, which nothing tested before. Expensive — the demo's example
|
||||
test rebuilds that list by hand, because a package cannot import a `main`, so the two can drift; the
|
||||
reference theme now has to style markup it never emitted before; and enabling tables changes how existing
|
||||
content renders, since a `|` line that used to come out as prose is now parsed.
|
||||
Revisit if: a sixth extension is wanted — which is a change to this decision and gets an ADR of its own,
|
||||
not a quiet line in the list.
|
||||
|
||||
Reference in New Issue
Block a user