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.

Inline marks in a heading

Inline code is the only mark a heading allows, at every level, and it round-trips unchanged: ## `batch` is the shape stays exactly that. Bold, italic, highlight, strikethrough, subscript, superscript, keystroke and links are not supported in a heading. The toolbar buttons and their shortcuts stay visible while the cursor is in a heading, but they do nothing there.

A mark arriving from markdown is stripped and the heading text kept, so ## **Bold** heading is stored as ## Bold heading. A link loses its destination and keeps only its text — put the link in the prose under the heading instead. An image is not a mark, and an image on a heading’s line removes the whole heading, text included; give an image a line of its own. Inline math is not a mark either, and it survives in a heading as inline code does.

Heading anchors

Every heading from level 1 to level 5 is given an id, generated from its text when the site is built: lower case, words joined by hyphens, punctuation dropped. The slugifier does a little more than that — & becomes and, camelCase is split (fooBar becomes foo-bar) and accented letters are transliterated (ü becomes ue) — so for anything other than plain words, check the built page rather than guessing. That id is what a same-page link targets, and what a cross-page pageid:<id>#section-slug link targets. A custom {#id} or {id="…"} on a heading is not supported: it is dropped from a CMS page body and from template markdown alike, so the generated id is the only one a heading has.

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, with no > and no blank line — and note that this line does not take the .class shorthand a heading does. Only that line is the quote’s: a {…} inside the quote’s text is text.

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

A quote can hold more than one paragraph. The blank > line that separates them is kept, so a two-paragraph quote such as the source above reads back as two paragraphs after a save, and every line of a heading, code block, list, table or alert inside a quote carries the > prefix as well.

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, and (C), (TM) and (R) are swapped too, so their letter case is lost. Wrap the literal in backticks when you mean the characters themselves. The swaps are for display only: the stored text keeps what you typed, and the editor shows it as typed. Nothing you wrote is ever dropped — the ellipsis needs exactly three dots, so .. and .... render as written, and so do !!!!, ???? and ,,.