This page is a compact fixture for reviewing article typography, spacing, syntax highlighting, and embedded MDX content in one place.

Heading level one

Use a single h1 sparingly inside posts because the article template already renders the post title.

Heading level two

Level two headings are included in the table of contents and receive stable anchor links from their text.

Heading level three

Use h3 for subsections inside a major section.

Heading level four

Use h4 when a subsection needs another layer of structure.

Heading level five

Use h5 for dense reference material.

Heading level six

Use h6 only when the hierarchy is already unavoidable.

Paragraphs and emphasis

Paragraphs should stay comfortable to read at the default measure. This paragraph includes strong emphasis, italic emphasis, and inline code so their rhythm can be checked together.

Links should be readable in body copy, whether they point to the home page or to an external reference like MDX.

Soft line breaks stay within the same paragraph. This sentence follows the previous line in source.

Lists

Unordered lists are useful for compact scans:

• Start with the strongest item.
• Keep each item parallel.
• End before the list becomes a paragraph with bullets.

Ordered lists communicate sequence:

1. Write the invariant down.
2. Encode it in the smallest useful abstraction.
3. Delete the comment that the code now enforces.

Nested content should still breathe:

• Runtime behavior
  • Latency budget
  • Failure mode
• Authoring behavior
  • Review path
  • Migration cost

Blockquotes

Good design-system documentation makes the correct thing easier to copy than the incorrect thing.

Blockquotes can also contain multiple paragraphs.

First, state the principle.

Then show the concrete tradeoff that makes the principle useful.

Code

Inline code works well for identifiers like getPost, slugify, and HighlightedCodeProvider.

type MarkdownFixture = {
  slug: string;
  headings: string[];
  hasCodeExamples: boolean;
};

const fixture: MarkdownFixture = {
  slug: "design-system",
  headings: ["Lists", "Blockquotes", "Code"],
  hasCodeExamples: true,
};

fn reading_time(words: usize) -> usize {
    (words / 225).max(1)
}

Plain text blocks keep logs, terminal output, and notes legible without syntax highlighting.

Mermaid diagrams

Mermaid fences render diagrams while keeping the source readable in Markdown.

flowchart LR
  Draft[Write MDX] --> Load[Load post metadata]
  Load --> Render[Render article]
  Render --> Diagram[Hydrate Mermaid diagram]

Rules and media

Horizontal rules separate distinct reference groups.

Images should scale with the article column and keep useful alternative text.

Tables and HTML

Raw HTML is available when a CommonMark primitive is not enough.

MDX components

MDX can render JSX alongside Markdown when a post needs a bespoke example.