Basic Formatting

Everything on this page is produced in the CMS by the standard text controls at the left of the editor toolbar — the block-type dropdown and the strip of mark buttons beside it. Each has a keyboard shortcut, and the complete keymap is on Keyboard Shortcuts. What follows is the format those controls write.

Headings

Headings run from ## to ######.

## Section heading
### Sub-section
#### Smaller still

This is not merely advice — it is what the editor enforces. The block-type dropdown offers Paragraph and Heading 2 through Heading 6, and nothing else; Heading 1 is deliberately absent, and the shortcuts follow the same range, Mod-Shift-2 through Mod-Shift-6, with Mod-Shift-0 returning a block to a paragraph.

Heading anchors

Every heading from level 1 to level 5 is given an id, slugified from its text: lower case, words joined by hyphens, punctuation dropped. That id is what a same-page link targets, and what a cross-page pageid:<id>#section-slug link targets.

Two behaviors worth knowing. Two headings with the same text get distinct ids — the first keeps the plain slug, the second gets -1, the third -2, and so on. And every rendered heading also carries tabindex="-1", so that following an anchor link moves keyboard focus to the heading rather than leaving it stranded at the top of the document.

This page is its own proof: jump to Smart typography resolves against the id generated for that heading. Because level 6 gets nothing, a ###### heading can never be the target of a link — if you want to link to it, promote it.

Emphasis and inline marks

The Result column below is live output, not a screenshot.

Highlight

==text== renders a <mark>: like this.

Keyboard keys

Double square brackets render a key cap.

Press [[Ctrl]] + [[C]] to copy, or [[Cmd]] + [[C]] on a Mac.

How it renders

Press Ctrl + C to copy, or Cmd + C on a Mac.

Links

A link is [text](url), and attributes go straight after the closing parenthesis with no space between them: this oneopens in a new tab. Internal links use the pageid: scheme rather than a path, and the heading ids described above are what an #anchor fragment points at — both on this page and, via pageid:<id>#anchor, on another one. Links and Internal Links covers the whole scheme, including what happens when a target page is not published.

Blockquotes

> Quote line 1
>
> Quote line 2

How it renders

Quote line 1 Quote line 2

Quotes nest with > >. To attach an attribute, put it on a line of its own directly after the quote — and note that a blockquote reads that line with a stricter parser than a heading does:

> Words worth quoting
{class="pull-quote"}

One round-trip loss to plan around: the blank > line that separates two paragraphs inside a quote is not preserved. Open a page carrying the two-paragraph quote above in the editor, make any change, and it is re-serialized as a single > line — the quote comes back as one paragraph. If a quote genuinely needs two paragraphs, keep it as two adjacent blockquotes.

Horizontal rules

Three hyphens on a line of their own, with a blank line above them:

---

How it renders

Line breaks

A line break inside a paragraph — as opposed to a new paragraph — is written as a trailing backslash at the end of the line, or as a literal <br>. In the editor, both Mod-Enter and Shift-Enter insert one.

Smart typography

The renderer has markdown-it’s typographer enabled, so plain ASCII punctuation is upgraded on the way out. Write the plain form; the right-hand column is what your readers see.

The last four are the ones people miss, because they fire in ordinary prose: a sentence about a (c) register or a shell flag written as +- will come out as a symbol. Wrap the literal in backticks when you mean the characters themselves.