Flavors and Renderers

The Lineage

There is no single Markdown. John Gruber's original 2004 Markdown.pl had no formal specification, so every implementation guessed at the edge cases differently. CommonMark exists to end that.

Write to CommonMark, add GFM's five extensions when the target is a Git forge, and treat everything else as opt-in for a pipeline you control.

Feature Support

The single most portable subset: ATX headings, paragraphs, - bullets, 1. ordered lists, **bold**, *italic*, backtick code spans, fenced code blocks, inline links, images, and blockquotes. That set renders identically everywhere.

MDX Specifics

MDX compiles Markdown into a component tree, so it is a superset syntactically and a subset practically: some Markdown that works elsewhere is a syntax error in MDX.

import Callout from "./Callout";

# Heading

<Callout type="warning">
  A component, with **Markdown** inside it.
</Callout>

The answer is {1 + 2}.

What changes:

• A bare < or { in prose is parsed as JSX and must be escaped or wrapped in a code span. This breaks a lot of copied Markdown.
• Raw HTML is JSX, so attributes are camelCase and class becomes className.
• Every tag must be closed, so <br> must be <br />.
• Indented code blocks are unreliable. Always use fences.
• HTML comments do not work. Use {/* a JSX comment */}.

MDX 2 and 3 are stricter than MDX 1, and the usual migration failure is an unescaped < or a self-closing tag written without the slash.

Renderer Libraries

Sanitizing matters as much as parsing. If Markdown from an untrusted source reaches a browser, run the HTML through a sanitizer such as DOMPurify or rehype-sanitize, or disable raw HTML in the parser. A renderer that passes HTML through is an XSS hole.

Linting

markdownlint is the de facto linter, available as a CLI, a VS Code extension, and a pre-commit hook. Rules are identified as MD###.

npx markdownlint-cli2 "**/*.md"
npx markdownlint-cli2 --fix "**/*.md"

{
  "default": true,
  "MD013": { "line_length": 100, "code_blocks": false },
  "MD033": { "allowed_elements": ["details", "summary", "kbd", "img"] },
  "MD041": false
}

The rules people most often relax:

Formatting

prettier formats Markdown out of the box and is the pragmatic choice, since most repositories already run it.

npx prettier --write "**/*.md"
npx prettier --check "**/*.md"

{
  "proseWrap": "preserve",
  "tabWidth": 2
}

What it normalizes: bullet markers to -, emphasis to *, heading style to ATX, table alignment, and list indentation. proseWrap is the setting to decide deliberately.

• "preserve" leaves your line breaks alone. The safe default.
• "always" hard wraps to printWidth, which produces enormous diffs on any edit.
• "never" joins each paragraph onto one line.

Run the formatter and the linter in that order, and let the formatter own anything the linter only complains about cosmetically. Two tools fighting over the same rule is worse than either alone.