# Markdown reference aardvark renders Markdown with [markdown-it](https://github.com/executablebooks/markdown-it-py), following the [CommonMark](https://commonmark.org) 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 `######`: ```markdown # 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](/authoring/templating/) 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 `\`: ```markdown 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 ```markdown **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: ```markdown "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 (c), (r), and (tm). ## Links ```markdown 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 and emails like . [mantine]: https://mantine.dev ``` renders, live: 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 and emails like . [mantine]: https://mantine.dev ## Inline HTML Raw HTML passes straight through, which covers the few things CommonMark leaves out: ```html Press Cmd + K. You can highlight text, write H2O and E = mc2, and define HTML. ``` renders, live: Press Cmd + K. You can highlight text, write H2O and E = mc2, and define HTML. A `
` element makes a native, no-JavaScript disclosure: ```html
Show more Hidden content that expands when you click the summary.
``` renders, live:
Show more Hidden content that expands when you click the summary.
## Blockquotes aardvark renders every Markdown blockquote as a callout island rather than a plain `
`. A bare `>` becomes the same untitled notification that [`{% aside %}`](/components/aside/) emits, and the body is full Markdown: ```markdown > A blockquote renders as a callout. The body is full Markdown: > > - **formatting** and `inline code` > - lists, too ``` renders, live: > A blockquote renders as a callout. The body is full Markdown: > > - **formatting** and `inline code` > - lists, too ### GitHub-style alerts Begin a blockquote with an alert marker — `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!CAUTION]` — and it renders as a [callout](/components/callout/) with a matching color and title: ```markdown > [!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: > [!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. ## Lists **Unordered** lists accept `-`, `*`, or `+` as the marker: ```markdown - 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: ```markdown 1. Step one 2. Step two 3. Step three ``` renders, live: 1. Step one 2. Step two 3. Step three 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: ```markdown 5. This list starts at five 6. and counts on from there ``` renders, live: 5. This list starts at five 6. and counts on from there Top-level numbered lists render as a [Steps](/components/steps/) timeline by default — the numbered-badge layout above. Set `steps: false` in `aardvark.config.yaml` to keep plain `
    ` 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: ```markdown 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: 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. ### 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: ```markdown - [x] Draft the page - [ ] Review it with the team - [ ] Ship it, then update `CHANGELOG.md` and **announce** ``` renders, live (try toggling one): - [x] 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: ```markdown 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: ```markdown | Element | Example | Done | | :----------- | :-------------------------: | -----: | | Bold | `**bold**` | Yes | | A link | [docs](https://mantine.dev) | Yes | | Escaped pipe | a \| b | Yes | ``` renders, live: | Element | Example | Done | | :----------- | :-------------------------: | -----: | | Bold | `**bold**` | Yes | | A link | [docs](https://mantine.dev) | Yes | | Escaped pipe | a \| b | Yes | ## 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: ````markdown ```python def greet(name): return f"Hello, {name}!" ``` ```` renders, live: ```python def greet(name): return f"Hello, {name}!" ``` ```json { "name": "aardvark", "version": "1.0.0" } ``` ```bash vark build && vark dev ``` Indenting a block by four spaces also makes a code block: ```markdown 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](https://mermaid.js.org) — 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: ````markdown ```mermaid graph TD A[Write Markdown] --> B{vark build} B --> C[HTML pages] B --> D[Search index] ``` ```` renders, live: ```mermaid 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 `
    `, so it still
reads sensibly if scripts are disabled. See the [Mermaid docs](https://mermaid.js.org) for the
syntax of every diagram type.

## Horizontal rules

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

```markdown
---
```

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:

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

renders, live:

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

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:

```markdown
![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:

![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)

## 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:

```markdown
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[^note].

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

## Escaping and literals

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

```markdown
\*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: New. See
[Templating & data](/authoring/templating/) for the full rules on showing literal tag syntax.

## 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](/components/badge/)** for labels, statuses, and counts:


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


renders, live: filled New Beta 9

A **[callout](/components/callout/)** is an admonition box, available in four severities:


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


renders, live:


Your changes were saved.



This setting only applies to new projects.



This overwrites uncommitted local changes.



Deleting a project cannot be undone.


An **[aside](/components/aside/)** is a lighter callout with a Markdown body:




The body renders as **Markdown**, including lists and `inline code`.




A **[button](/components/button/)** renders a link or an action:

Read the quickstart

An **[accordion](/components/accordion/)** wraps collapsible panels, each with a full Markdown body:

What is aardvark?

A Mantine-powered static site generator. This panel body is full **Markdown**.


How do I add a page?

Drop a Markdown file in `content/` with front matter and it joins the navigation automatically.