Case‑Sensitive or Case‑Insensitive Markdown Link References: Choosing Spec Compliance vs. Legacy Compliance

Recommended default

Default to CommonMark case-insensitive matching for link reference definitions. Provide a case-sensitive mode only as an explicit, documented opt-in flag for legacy content.

Confirmed behavior versus likely legacy risk

Confirmed: CommonMark normalizes reference labels by trimming leading and trailing whitespace and applying Unicode case folding before comparison. As a result, [Foo], [foo], and [FOO] resolve to the same definition, and when multiple definitions collide under folding, the first definition in the document wins.

Likely legacy risk: documents authored for case-sensitive engines may depend on labels that differ only by case. Under the spec default, those labels collapse into a single reference and later definitions are silently ignored. This is the only scenario that justifies a legacy mode, and because it is an extension beyond CommonMark, it should never be the default.

Migration and versioning checklist

1. Audit existing documents for definitions whose labels differ only by case, or for references whose targets change when case folding is applied.
2. If collisions exist, either rewrite labels to be unique or enable the opt-in legacy flag for those files.
3. Document the default, the exact configuration key, whether normalization is full Unicode case folding or ASCII-only, and the first-wins duplicate rule.
4. Treat any default change from case-sensitive to case-insensitive as a breaking change; release it as a major version or behind a migration flag that emits warnings.

Practical verification

Before changing defaults, confirm behavior with a minimal test file:

[Foo]: /a
[foo]: /b
[FOO]: /c

See [Foo], [foo], and [FOO].

Under CommonMark defaults, all three links resolve to /a. Under a case-sensitive legacy mode, they resolve to /a, /b, and /c respectively.

One diagnostic that changes the advice

Does your current corpus contain link reference definitions whose labels differ only by case? If yes, the legacy opt-in is mandatory for those documents and should be documented prominently. If no, the spec-compliant default is safe and the legacy flag can remain experimental.