Documentation

Writing and formatting

Format text with the toolbar, markdown you type, the slash menu and the Insert menu.

On this page 7

Type as you would in any document. There are four ways to format:

  • the toolbar above the page
  • markdown as you type, such as ## for a heading or **bold**
  • the slash menu: type / on an empty line
  • keyboard shortcuts. See Keyboard shortcuts.

Hover over any toolbar button to see its name, its shortcut and the markdown you can type instead.

The toolbar

Button Does Or type
Undo / Redo Steps back or forward
H2, H3, H4 Heading, subheading, minor heading ## , ### , ####
Bold, Italic, Strikethrough Text styles **text**, *text*, ~~text~~
Inline code code within a sentence `code`
Link Adds or edits a link
Bulleted, numbered, task list Lists - , 1. , [ ]
Quote A block quote >
Callout A highlighted note, tip or warning
Code block Code with a copy button ```
Table A 3 × 3 table with a header row
Image or video Embeds media from a URL
Divider A horizontal line ---
Insert Maths, diagrams, tabs, footnotes and more

Select text and press the Link button (or ⌘K / Ctrl+K). Paste a full URL or a path on your site, such as /billing/plans. Leave the URL empty to remove the link. Web addresses you type become links on their own.

Callouts

Callouts draw attention to a note. The Callout button adds a tip; with the cursor inside one, pick its type from the bar that appears: note, tip, important, warning, caution or danger.

Code blocks

With the cursor in a code block, a bar lets you set:

  • Language, for syntax highlighting. Pick a suggestion or type any language name.
  • Tab label. Code blocks next to each other that all have a tab label show as one block with tabs on your site, which is handy for showing the same example in several languages.

A code block with the language mermaid renders as a diagram on your live site.

Images and video

The Image or video button asks for:

  • URL: a link to the file. Images must be hosted elsewhere, such as your own website or a public bucket; there's no upload. Links to .mp4, .webm, .ogg or .mov files play as video.
  • Alt text: describes the image for people who can't see it.
  • Caption: shown under the image.

YouTube and Vimeo links on a line of their own become embedded players on your live site.

The slash menu

Type / at the start of an empty line to open Blocks. Keep typing to filter it, use ↑ and ↓ to choose, then press Enter or Tab. Esc closes it. It offers headings, callouts, code blocks, tables, lists, quotes, dividers and everything in the Insert menu.

The Insert menu

Insert adds richer content. Most of it renders fully on your live site rather than in the editor; see Advanced content.

Item What it adds
Task list Checkboxes
Diagram A Mermaid flowchart
Code tabs The same example in several languages
Tabs Switchable panels
Maths block A KaTeX equation
Inline maths An equation within a sentence
Footnote A numbered note at the end of the page
Alert, Button, Badge, Embed Ready-made macros
Callout with title A callout component with its own heading
Icon An inline icon
HTML A raw HTML block