# docbin markdown reference

docbin renders GitHub-Flavored Markdown and adds callouts, structural and interactive directives, an embed allowlist, tabs, and a frontmatter block. This is the complete syntax reference for every element the renderer understands.

## Base markdown

GitHub-Flavored Markdown is supported in full: tables, strikethrough with `~~text~~`, and task lists.

```md
- [x] done
- [ ] not done
```

Math renders through KaTeX. Use `$...$` for inline math and `$$...$$` for a block:

```md
The area is $\pi r^2$.

$$
\int_0^1 x^2 \, dx = \tfrac13
$$
```

Diagrams render through Mermaid. Use a fenced block with the `mermaid` language:

````md
```mermaid
graph LR
  A --> B
```
````

Fenced code blocks are syntax-highlighted. Alongside the usual languages, docbin adds three custom grammars: `log`, `westmyth`, and `accesslog`.

## Callouts

A callout is a fenced container opened and closed with three colons. The word after the colons is the callout type:

```md
:::note
Body content here. Markdown inside the body is rendered.
:::
```

There are ten types, each with its own icon and accent color: `note`, `info`, `tip`, `warning`, `caution`, `important`, `success`, `danger`, `question`, `quote`.

The heading defaults to the type name. Override it with a `title` attribute:

```md
:::warning{title="Heads up"}
Custom title above the body.
:::
```

## GFM alerts

GitHub-style blockquote alerts also render as callouts. The tag is uppercase and goes on the first line:

```md
> [!NOTE]
> This renders as a note callout.
```

Five alert tags are recognized: `[!NOTE]`, `[!TIP]`, `[!WARNING]`, `[!IMPORTANT]`, `[!CAUTION]`.

## Structural directives

These use the same three-colon container syntax as callouts.

`details` is a collapsible disclosure. The body is hidden until the reader opens it:

```md
:::details{title="Show more"}
Hidden until expanded.
:::
```

`steps` turns a markdown list into a numbered step sequence:

```md
:::steps
1. First step.
2. Second step.
3. Third step.
:::
```

`compare` lays out two panes side by side. Separate the panes with a `---` horizontal rule:

```md
:::compare
Left pane content.

---

Right pane content.
:::
```

`figure` wraps content as a figure with an optional caption from the `title` attribute:

```md
:::figure{title="Diagram 1"}
![alt](https://example.com/image.png)
:::
```

`cards` is a grid wrapper. Each `card` inside it is one cell. Because a card nests inside cards, the outer container opens with four colons and the inner cards use three:

```md
::::cards
:::card{title="First"}
Body of the first card.
:::

:::card{title="Second"}
Body of the second card.
:::
::::
```

The four-colon marker is the general rule for nesting: when one container holds another, give the outer one an extra colon so the parser knows where it closes.

## Interactive

A badge is inline. It takes a label in brackets and an optional `variant`:

```md
Status: :badge[stable]{variant=success}
```

The ten badge variants match the callout types: `note`, `info`, `tip`, `warning`, `caution`, `important`, `success`, `danger`, `question`, `quote`. The default variant is `note`.

An embed renders a sandboxed iframe. Put the URL on its own line inside the container:

```md
:::embed
https://www.youtube.com/watch?v=dQw4w9WgXcQ
:::
```

Only these hosts are allowed: `youtube.com`, `www.youtube.com`, `youtu.be`, `youtube-nocookie.com`, `www.youtube-nocookie.com`, `vimeo.com`, `www.vimeo.com`, `codepen.io`, `codesandbox.io`, `stackblitz.com`. A URL from any other host renders as a plain link instead of an iframe.

Tabs group sections behind a tab strip. Each `@tab` line starts a new tab and names its label:

````md
:::tabs
@tab npm
```sh
npm install docbin
```

@tab pnpm
```sh
pnpm add docbin
```
:::
````

## Frontmatter

An optional YAML block at the very top of the document, fenced by `---`, sets document options:

```md
---
title: My Document
description: A short summary for search engines.
theme: dark
toc: true
toc_depth: 3
toc_title: Contents
toc_side: right
author: Ada Lovelace
date: 2026-06-25
tags:
  - reference
  - markdown
reading_time: true
hide_title: false
---
```

The twelve recognized keys:

- `title` (string) document title
- `description` (string) meta description for search and link previews
- `theme` (string) color theme name
- `toc` (boolean) show the table of contents
- `toc_depth` (2 or 3) deepest heading level included in the table of contents
- `toc_title` (string) heading shown above the table of contents
- `toc_side` (left or right) which side the table-of-contents rail sits on
- `author` (string) author name
- `date` (string) document date
- `tags` (array) list of tags
- `reading_time` (boolean) show an estimated reading time
- `hide_title` (boolean) suppress the rendered title header

## Unknown directives

A `:::name` directive that docbin does not recognize is not an error. It degrades to a neutral wrapper and its body still renders, so an unknown name never breaks the document.