Markdown reference

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

That is the whole contract. This page lists what it accepts, and — just as usefully — what it does not.

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.

There is no visible permalink icon. The anchors exist so that #fragment links and the table of contents work.

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');

There is no syntax highlighting. Code blocks are styled — monospace, background, horizontal scroll, and print-safe — but tokens are not coloured, and no highlighting JavaScript is shipped to the browser. The language class is preserved so highlighting can be added later without a content change.

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.

This is deliberate. Pages are markdown; the rendered output is ours to keep safe. A docs platform that pipes arbitrary HTML from a file straight into a reader's browser has handed every page a script injection point, and no amount of care on your side removes that from the platform's side.

In practice the markdown covers what HTML was usually reached for:

Site settings are validated on the same principle: logo URLs, footer link URLs, theme colours, and redirect targets are checked against an allow-list when written and checked again when rendered.

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.

Typographic substitution is deliberately off so that code, command lines, and configuration snippets written outside a code fence are never quietly corrupted.

Linking between pages

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

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

The renderer does not rewrite relative links. A link written as install.md is emitted verbatim, and because Docsary serves raw markdown at any .md URL, that link resolves to a plain-text file rather than the rendered page. Absolute paths avoid the whole class of problem, and they stay correct when a page moves between folders in the navigation.

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