--- title: Markdown reference description: The exact markdown syntax Docsary supports — CommonMark plus tables, strikethrough, and admonitions — and what it deliberately does not. order: 1 --- # 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. | Syntax | Result | | --- | --- | | `*italic*` or `_italic_` | *italic* | | `**bold**` | **bold** | | `~~strikethrough~~` | ~~strikethrough~~ | | `` `inline code` `` | `inline code` | | `[link](/quickstart)` | [link](/quickstart) | | `[ref][1]` with `[1]: https://example.com` | reference-style links | 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 `
`. ## Headings and anchors ```markdown # 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 ```markdown - 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"`: ````markdown ```js const site = await fetch('/v1/sites'); ``` ```` ```js 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 ```markdown | Column | Aligned right | | :--- | ---: | | value | 42 | ``` | 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 ```markdown > A quotation. --- ``` > A quotation. --- ## Admonitions Four callout containers are available. Open with `:::kind`, close with `:::`. ```markdown :::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: :::info Informational aside. ::: :::warning Something to be careful about. ::: :::danger Something that will break things. ::: :::success A confirmation or a good outcome. ::: 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 ```markdown ![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/`; see [Images and assets](/writing/assets). ## HTML in markdown **HTML written in a page renders as literal text, not as HTML.** A `
` block or an inline `` 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: | Instead of | Write | | --- | --- | | `
` with `
` | The image, then a line of `*italic caption text*` under it | | `` | A plain image — every image is fitted to the content width | | ``, ``, `` | `` `Ctrl` `` in backticks, or `**bold**` | | `
` | An [admonition](#admonitions) | | `
` | Two trailing spaces, or a blank line for a new paragraph | 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. | Syntax | Status | | --- | --- | | Raw HTML (`
`, `
`, ``) | Rendered as literal text — see [HTML in markdown](#html-in-markdown) | | Task lists (`- [ ]`) | Not supported | | Footnotes (`[^1]`) | Not supported | | Definition lists | Not supported | | Abbreviations (`*[HTML]:`) | Not supported | | Emoji shortcodes (`:smile:`) | Not supported — paste the character | | Math (`$x^2$`, KaTeX) | Not supported | | MDX, JSX, or components | Not supported | | Front-matter-driven layouts | Not supported | | Smart quotes and dash substitution | Disabled — `"` stays `"`, `--` stays `--` | 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: ```markdown 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](/versions).