Markdown reference

Docsary renders standard CommonMark, plus tables, strikethrough, autolinking, heading anchors, and admonition containers. Typographic substitution is off.

Text

Standard CommonMark inline syntax works.

Line breaks follow CommonMark: a single newline is a soft break, a blank line starts a paragraph, and two trailing spaces or a trailing backslash force a <br>.

Headings and anchors

# Page title
## A section
### A subsection

Every heading from # to ###### receives an id derived from its text: lowercased, spaces replaced with hyphens, non-ASCII characters percent-encoded. Repeated heading text gets a numeric suffix — a second "Options" becomes #options-1.

Use heading anchors for links to sections.

The On this page table of contents is built from h2, h3, and h4 only. h1 is the page title and is excluded; h5 and h6 are too deep to list. The table of contents is rendered only when a page has at least two qualifying headings — short pages get no rail.

Lists

- one
- two
  - nested
1. first
2. second
   - mixed nesting works

Task lists are not supported. - [ ] todo renders literally as [ ] todo. Use a table or plain list instead.

Code

Fenced code blocks carry their language through to the HTML as class="language-js":

```js
const site = await fetch('/v1/sites');
```

const site = await fetch('/v1/sites');

Code blocks use monospace text and horizontal scrolling. Language labels are retained, but syntax highlighting is not included.

Indented code blocks (four spaces) work too.

Tables

| Column | Aligned right |
| :--- | ---: |
| value | 42 |

Column alignment (:---, :---:, ---:) is supported and emitted as inline text-align styles. Wide tables scroll horizontally inside their own container rather than pushing the page sideways.

Blockquotes and rules

> A quotation.

---

A quotation.

Admonitions

Four callout containers are available. Open with :::kind, close with :::.

:::info
Informational aside.
:::

:::warning
Something to be careful about.
:::

:::danger
Something that will break things.
:::

:::success
A confirmation or a good outcome.
:::

They render as:

The content inside a container is full markdown — lists, code blocks, links, and nested emphasis all work. info, warning, danger, and success are the only four kinds; any other word after ::: is not a container and will render as literal text.

Images

![Alt text](/assets/img/diagram.png "Optional title")

Images are constrained to the content width and given rounded corners. Upload files through the assets API and reference them at /assets/<path>; see Images and assets.

HTML in markdown

HTML written in a page renders as literal text, not as HTML. A <figure> block or an inline <kbd> tag appears on the page as the characters you typed, angle brackets and all.

Use these Markdown alternatives:

Automatic links

Autolinking is on. A bare URL or a bare domain in the text becomes a link:

• https://example.com becomes a link.
• example.com also becomes a link, pointing at http://example.com.

If you need a literal domain that is not a link, wrap it in backticks.

Not supported

These are common in other docs tools and are silently not processed here. Each renders as literal text.

Linking between pages

Write internal links as site-relative absolute paths, without the .md extension:

See the [API reference](/api) and [Versions](/versions).

Relative links are preserved as written. A link ending in .md opens the source, so use a site-relative path without that extension for the rendered page.

Linking into a non-default version needs the version prefix — /0.9/guide/install. See Versions.