Markdown reference

A live demo of every Markdown element aardvark renders — headings, text styles, lists, tables, blockquotes, code, diagrams, images, and footnotes — plus the built-in tags.

aardvark renders Markdown with markdown-it, following the CommonMark spec with tables, strikethrough, footnotes, smart typography, and automatic links turned on. This page shows the source for every element next to its live result — copy any block straight into your own pages.

Headings

Six levels, from # to ######:

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6

renders, live:

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

Levels 1–4 get a stable id, a permalink that fades in when you hover, and an entry in the On this page table of contents; levels 5 and 6 render but stay out of the TOC. (Because the six lines above are real headings, you will see levels 1–4 appear in this page’s TOC.) Pin a custom id by ending a heading line with {#my-id} — see Templating & data for more.

Paragraphs and line breaks

Separate paragraphs with a blank line. A single newline just soft-wraps. For a hard line break, end a line with two trailing spaces or a backslash \:

First paragraph.

Second paragraph,\
forced onto a new line within the same paragraph.

renders, live:

First paragraph.

Second paragraph,
forced onto a new line within the same paragraph.

Text formatting

**Bold** and __bold__, *italic* and _italic_, ***bold italic***,
~~strikethrough~~, and `inline code`.

renders, live:

Bold and bold, italic and italic, bold italic, strikethrough, and inline code.

Smart typography

With the typographer on, straight quotes curl, hyphens become dashes, and a few symbols are replaced automatically:

"Double" and 'single' quotes, an en -- dash, an em --- dash, an ellipsis...,
plus (c), (r), and (tm).

renders, live:

“Double” and ‘single’ quotes, an en – dash, an em — dash, an ellipsis…, plus ©, ®, and ™.

Links

An [inline link](https://mantine.dev), a [link with a title](https://mantine.dev "Mantine docs"),
and a [reference-style link][mantine]. Bare URLs auto-link: https://commonmark.org — as do
angle-bracketed ones like <https://mantine.dev> and emails like <hello@example.com>.

[mantine]: https://mantine.dev

renders, live:

An inline link, a link with a title, and a reference-style link. Bare URLs auto-link: https://commonmark.org — as do angle-bracketed ones like https://mantine.dev and emails like hello@example.com.

Inline HTML

Raw HTML passes straight through, which covers the few things CommonMark leaves out:

Press <kbd>Cmd</kbd> + <kbd>K</kbd>. You can <mark>highlight</mark> text, write H<sub>2</sub>O
and E = mc<sup>2</sup>, and define <abbr title="HyperText Markup Language">HTML</abbr>.

renders, live:

Press Cmd + K. You can highlight text, write H₂O and E = mc², and define HTML.

A <details> element makes a native, no-JavaScript disclosure:

<details>
<summary>Show more</summary>

Hidden content that expands when you click the summary.

</details>

renders, live:

Blockquotes

aardvark renders every Markdown blockquote as a callout island rather than a plain <blockquote>. A bare > becomes the same untitled notification that {% aside %} emits, and the body is full Markdown:

> A blockquote renders as a callout. The body is full Markdown:
>
> - **formatting** and `inline code`
> - lists, too

renders, live:

GitHub-style alerts

Begin a blockquote with an alert marker — [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], or [!CAUTION] — and it renders as a callout with a matching color and title:

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP]
> A helpful suggestion for doing things better.

> [!IMPORTANT]
> Key information users need in order to succeed.

> [!WARNING]
> Urgent information that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes of an action.

renders, live:

Lists

Unordered lists accept -, *, or + as the marker:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

renders, live:

• First item
• Second item
  • Nested item
  • Another nested item
• Third item

Ordered lists use 1., 2., and so on:

1. Step one
2. Step two
3. Step three

renders, live:

A numbered list can also start at a custom number — the first item sets the starting value and the rest count on from there. Keep it as its own list (separated by intervening text), since adjacent numbered items merge into one list:

5. This list starts at five
6. and counts on from there

renders, live:

Top-level numbered lists render as a Steps timeline by default — the numbered-badge layout above. Set steps: false in aardvark.config.yaml to keep plain <ol> numbering instead; nested numbered lists and bullet lists are left as-is either way.

Mixed and nested, with a list item that carries several blocks:

1. Ordered parent
   - Unordered child
   - Another child
2. Second parent

   A second paragraph that belongs to item 2.

   > And a blockquote, indented to stay inside the item.

renders, live:

Task lists

Begin a list item with [ ] or [x] and it renders as a Mantine checkbox — checked when the brackets hold an x (upper- or lower-case). Everything after the marker is the label, so inline formatting like code and emphasis works inside it. The boxes are interactive — a reader can toggle them — but the state isn’t stored, so it resets on reload to match the source:

- [x] Draft the page
- [ ] Review it with the team
- [ ] Ship it, then update `CHANGELOG.md` and **announce**

renders, live (try toggling one):

• Draft the page
• Review it with the team
• Ship it, then update CHANGELOG.md and announce

Definition lists (not enabled)

Definition lists are not turned on, so the Term / : Definition syntax falls back to plain text rather than rendering as term/definition pairs:

Term
: Definition

renders, live (note the leading colon is kept verbatim):

Term : Definition

Tables

Pipe tables come from the enabled table rule. A colon in the divider row sets each column’s alignment — left (:---), center (:--:), or right (---:). Cells accept inline formatting:

| Element      |          Example            |   Done |
| :----------- | :-------------------------: | -----: |
| Bold         |        `**bold**`           |    Yes |
| A link       | [docs](https://mantine.dev) |    Yes |
| Escaped pipe |          a \| b             |    Yes |

renders, live:

Code

Inline code uses single backticks: print("hi"). To include a literal backtick, wrap the span in two backticks: `not code`.

A fenced block takes an optional language label. aardvark does not bundle a syntax highlighter, so blocks render as clean monospace and the language is preserved as a language-* class for any client-side highlighter you choose to add:

```python
def greet(name):
    return f"Hello, {name}!"
```

renders, live:

def greet(name):
    return f"Hello, {name}!"

{
  "name": "aardvark",
  "version": "1.0.0"
}

vark build && vark dev

Indenting a block by four spaces also makes a code block:

    This line is indented four spaces,
    so it renders as a code block.

renders, live:

This line is indented four spaces,
so it renders as a code block.

Diagrams

Label a fenced block mermaid and aardvark renders it to an inline SVG in the browser with Mermaid — flowcharts, sequence diagrams, Gantt charts, and more. The library is fetched only on pages that actually contain a diagram, and each diagram follows the page’s light/dark setting:

```mermaid
graph TD
  A[Write Markdown] --> B{vark build}
  B --> C[HTML pages]
  B --> D[Search index]
```

renders, live:

graph TD
  A[Write Markdown] --> B{vark build}
  B --> C[HTML pages]
  B --> D[Search index]

The diagram source stays in the page as plain text inside a <pre class="mermaid">, so it still reads sensibly if scripts are disabled. See the Mermaid docs for the syntax of every diagram type.

Horizontal rules

Three or more -, *, or _ on their own line draw a divider:

---

renders, live:

Images

Reference an image with ![alt text](path). Files in static/ are copied to the site root, so static/img/sample-square.svg is served at /img/sample-square.svg. SVG, PNG, and JPG all work the same way:

![A sample landscape](/img/sample-landscape.svg)

renders, live:

Add a title (shown on hover), make an image into a link by wrapping it, and reuse any static asset such as the site logo:

![Square thumbnail](/img/sample-square.svg "A square sample image")

[![A clickable thumbnail](/img/sample-square.svg)](https://mantine.dev)

![aardvark logo](/logo-light.svg)

renders, live:

Footnotes

Reference a footnote with [^label], then define it anywhere. All footnotes collect at the bottom of the page, each with a link back to where it was used:

Here is a numbered footnote[^1] and a named one[^note].

[^1]: The definition can sit right here in the source.
[^note]: Footnotes may contain **formatting** and [links](https://mantine.dev).

renders, live:

Here is a numbered footnote^[1] and a named one^[2].

Escaping and literals

Put a backslash before a Markdown character to render it literally:

\*not italic\*, \`not code\`, and 1\. not a list.

renders, live:

*not italic*, `not code`, and 1. not a list.

aardvark also runs its Python {% %} template tags before Markdown. A tag wrapped in a raw block prints verbatim — {% badge text=‘New’ %} — while the same tag left unwrapped renders live:

Built-in tags

Beyond standard Markdown, aardvark ships a handful of tags that expand to interactive Mantine components. Each has its own reference page; here is a quick look.

A badge for labels, statuses, and counts:

{% badge variant='light' color='grape' %}New{% endBadge %}

renders, live:

A callout is an admonition box, available in four severities:

{% callout title="All systems go" severity="success" %}
Your changes were saved.
{% endCallout %}

renders, live:

An aside is a lighter callout with a Markdown body:

A button renders a link or an action:

An accordion wraps collapsible panels, each with a full Markdown body: