Writing content in Markdown

Documentation articles, blog posts, changelog entries and legal pages are plain Markdown files. This page shows each style so you can check them after changing the design tokens.

Headings#

Start sections with a second-level heading (##). The page title is the only first-level heading, and it comes from the title field at the top of the file.

Third-level heading#

Use third-level headings inside a section.

Fourth-level heading

Fourth-level headings are the smallest style.

Links to a heading#

Every second- and third-level heading gets a small # link after its text. It appears when you point at the heading or reach it with the keyboard, and it stays visible on a touch screen. Copy that link to send someone to one section, or write it yourself: /docs/markdown-guide#tables.

The contents list#

An article with three or more second- and third-level headings gets an “On this page” list: beside the text on a wide screen, in a panel above it on a narrower one. Add toc: false at the top of a file to leave the list out of that article.

Text#

A paragraph can contain strong text, emphasis, inline code and links. Write links to other pages from the site root, for example /docs/design-system. The theme adds the base path for you when the site is served from a sub-path.

Lists#

• An unordered item.
• Another item.
  • A nested item.

1. A first step.
2. A second step.
3. A third step.

Code#

// A fenced code block with a language name is highlighted.
const entries = timeline.filter((entry) => entry.source === 'deploys');
console.log(entries.length);

The frame shows the language name and a copy button. A line that is longer than the block scrolls sideways inside it, and the page stays still:

curl --request GET --url "https://example.com/api/timeline?source=deploys&from=2026-10-01&to=2026-10-07&limit=50" --header "Accept: application/json" --header "Authorization: Bearer YOUR_API_KEY"

A block without a language name has no language label and no colors:

2026-10-07 09:14  deploys  Release 42 finished
2026-10-07 09:20  metrics  Sign-ups moved above the usual range

Tables#

A table that is wider than the page scrolls sideways inside its own frame.

Quotes and callouts#

A plain quote:

One calm view is worth more than five busy ones.

A quote whose first line is [!NOTE], [!TIP] or [!CAUTION] becomes a callout:

Note

Notes add context the reader may need.

Tip

Tips suggest a better way to do something.

Caution

Cautions warn about something that is easy to get wrong.

The marker can also stand on a line of its own, followed by a blank quote line:

Note

This callout starts after a blank line.

Rules#

Three dashes on their own line draw a rule.

Images#

Put images in the public/ folder and link to them from the site root, for example ![Alt text](/images/example.png). Always write alt text that says what the image shows.