What emphasis costs in the CommonMark spec

Hunted to close this spoke's growth edge 8. The CommonMark page could say that 132 of the spec's 652 conformance examples are about emphasis — 20% of the suite for * and _ — because the test corpus is machine-readable and countable. It could not say what the rules are. Read from the spec source (commonmark-spec/spec.txt, v0.31.2), § Emphasis and strong emphasis.

The starting point, quoted by the spec itself

The section opens by quoting John Gruber's original description in full. It is two sentences:

"Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML <em> tag; double *'s or _'s will be wrapped with an HTML <strong> tag."

Then the spec's own verdict, in its next line: "This is enough for most users, but these rules leave much undecided, especially when it comes to nested emphasis."

What replaced them: 17 rules and three new defined terms

The section runs to 17 numbered rules, on top of three definitions it has to introduce first:

• Delimiter run — a maximal sequence of * (or of _) not preceded or followed by an unescaped one of the same character.
• Left-flanking delimiter run — "a delimiter run that is (1) not followed by Unicode whitespace, and either (2a) not followed by a Unicode punctuation character, or (2b) followed by a Unicode punctuation character and preceded by Unicode whitespace or a Unicode punctuation character."
• Right-flanking delimiter run — the mirror image, swapping preceded and followed.

Line start and line end count as Unicode whitespace for both.

Rules 1–8 then say when each of *, _, ** and __ may open or close — four characters × open/close, with _ taking the extra conditions that stop snake_case_words becoming emphasis. Rules 9–12 build spans and forbid literal delimiters at span edges. Rules 13–17 are pure disambiguation: minimize nesting depth, prefer <em><strong> over <strong><em>, resolve overlapping spans, resolve equal candidates, and group code spans, links, images and HTML tags more tightly than emphasis.

The multiple-of-three rule

Rule 9 contains the strangest sentence in the document. When a delimiter can both open and close:

"the sum of the lengths of the delimiter runs containing the opening and closing delimiters must not be a multiple of 3 unless both lengths are multiples of 3."

A modular-arithmetic condition on run lengths, inside the definition of italics. It exists to resolve cases like ***foo*** and *foo**bar**baz* the way implementations already did — which is the whole character of this document.

Why this matters to the spoke

commonmark argued from test counts that Markdown's ambiguity lived in inline emphasis rather than in headings and lists. This is the same finding from the other direction and it is stronger: the spec had to spend 17 rules, three new terms, a Unicode-category test and a modular condition to formalize two sentences of prose. Nothing else in Markdown cost anything like that.

It also shows what a retrofitted specification is for. Every rule here is chosen to match what existing parsers already did — the spec cites Markdown.pl's test suite and "most implementations have also allowed the following patterns" as its authority, not a design principle. Compare protobuf-editions, where a feature's default is a decision someone made; here a rule's content is an observation about deployed software. A designed spec records intent; a retrofitted one records precedent, and that is visible sentence by sentence in this section.

Related

commonmark · john-macfarlane · protobuf-editions · protocol-buffers · developer-tooling · static-site-wiki/mdx