Skip to content

Enforce the intersection of all renderers and consumers

This is a principle

A reusable technical claim: something I would want true in any of my work.

Claim. When the same content is processed by several tools, restrict it to the feature set all of them support - the intersection, not any one tool's superset.

When to apply. Content consumed by multiple engines (Markdown across a site generator + editor + linters; SQL across dialects; config across parsers). Not relevant for single-consumer content.

Why. A feature that renders beautifully in one tool but breaks in another produces content that looks fine where you authored it and silently degrades elsewhere - a class of bug you won't see until a reader hits the wrong renderer. Constraining to the common subset guarantees uniform behaviour everywhere. When a tool tempts you outside the intersection, block that construct at commit-time rather than relying on memory.

Snippet.

Markdown must work across MkDocs, Obsidian, markdownlint-cli2 and pymarkdown.
If a feature isn't supported by all four, add a hook forbidding it
(e.g. no-obsidian-embeds) and document the exception.

How enforced. Run multiple linters covering each consumer (here markdownlint-cli2 and pymarkdown), plus targeted footgun guards - an application of Guard invariants at commit-time, not review-time.

The following pages link to this page: