# Directives

Callouts, steps, code tabs, cards, figures, FAQ, glossary and inline elements, each with its syntax and the result.

Directives extend Markdown with components. A container directive starts with three or more colons and a name on its
own line, and ends with a line of the same number of colons. A leaf directive (`::card`, `::figure`, `::snippet`) is one
line with two colons. Inline directives start with one colon.

Each section below shows the source, then what it renders.

:::warning[Unknown block directives fail the build.]
A typo such as `:::notes` stops `check` and `build` with the file name and the list of known directives. An unknown
inline directive is kept as text, so `ratio 3:2` stays as written.
:::

## Callouts

Four kinds, each with an alias:

| Directive | Alias | Tone |
|---|---|---|
| `:::note` | `:::info` | Information |
| `:::tip` | `:::success` | Positive |
| `:::warning` | `:::caution` | Warning |
| `:::danger` | `:::error` | Error |

The label in brackets becomes a bold lead at the start of the first paragraph. `{title="..."}` does the same.

```md
:::note[Before you start.]
You need an API key with write access.
:::

:::danger{title="Irreversible."}
Deleting a queue drops every job in it.
:::
```

:::note[Before you start.]
You need an API key with write access.
:::

:::danger{title="Irreversible."}
Deleting a queue drops every job in it.
:::

## Steps

Wrap `##` headings in `::::steps` to number them. Everything between two headings belongs to the step above. Use four
colons, so the container can hold fenced code and other directives.

````md
::::steps
## Install the CLI

```terminal
$ npm install -g rocket-cli
```

## Log in

Run `rocket login` and paste your key.
::::
````

::::steps
## Install the CLI

```terminal
$ npm install -g rocket-cli
```

## Log in

Run `rocket login` and paste your key.
::::

The step headings appear in the table of contents like other `##` headings.

## Code tabs

`:::code-group` turns its fenced blocks into tabs. The reader's choice is remembered across the site, so picking Go on
one page shows Go on the next one. Set the tab label with `label="..."` and a file name with `title="..."` in the fence
line.

````md
:::code-group
```go title="main.go" label="Go"
client := rocket.New(os.Getenv("ROCKET_KEY"))
```

```typescript title="index.ts"
const client = new Rocket(process.env.ROCKET_KEY);
```
:::
````

:::code-group
```go title="main.go" label="Go"
client := rocket.New(os.Getenv("ROCKET_KEY"))
```

```typescript title="index.ts"
const client = new Rocket(process.env.ROCKET_KEY);
```
:::

Without `label`, the tab shows the language name. See [Code blocks](./code-blocks.md) for single blocks and terminal
sessions.

## Link cards

`::card` is a leaf directive inside `:::cards`. `href` is required; relative links to Markdown files become page URLs.

```md
:::cards
::card[Frontmatter]{href="./frontmatter.md" description="Fields at the top of a page."}
::card[Code blocks]{href="./code-blocks.md" description="Languages, file names and terminals."}
:::
```

:::cards
::card[Frontmatter]{href="./frontmatter.md" description="Fields at the top of a page."}
::card[Code blocks]{href="./code-blocks.md" description="Languages, file names and terminals."}
:::

## Feature cards

`:::feature` is a container with an icon, a title, Markdown content and an optional link. Put feature cards inside
`::::cards` (four colons, since they contain three-colon containers).

````md
::::cards
:::feature[Search]{icon="search" href="../features/search.md" link="How search works"}
A Pagefind index built with the site.
:::

:::feature[Themes]{icon="palette"}
Accent, grays, radius, header and code colors per project.
:::
::::
````

::::cards
:::feature[Search]{icon="search" href="../features/search.md" link="How search works"}
A Pagefind index built with the site.
:::

:::feature[Themes]{icon="palette"}
Accent, grays, radius, header and code colors per project.
:::
::::

`icon` is a [Lucide](https://lucide.dev/icons/) icon name, for example `book-open`; it defaults to `circle`. The link
shows only when both `href` and `link` are set.

:::warning[Icon names are checked in build only.]
An unknown icon name passes `docsp check` and fails `docsp build`.
:::

## Procedure

`:::procedure` renders a numbered list as product steps, for end-user guides. Each item is `**Title**` followed by
text. The text is plain: links and formatting in it are dropped.

```md
:::procedure
1. **Open the settings** Choose the gear icon at the top right.
2. **Add a channel** Choose Email, then enter the sender address.
3. **Send a test** Check the inbox of the sender address.
:::
```

:::procedure
1. **Open the settings** Choose the gear icon at the top right.
2. **Add a channel** Choose Email, then enter the sender address.
3. **Send a test** Check the inbox of the sender address.
:::

## Figure

`::figure` shows an image with a caption, and an optional second image for dark mode. Paths are relative to the
Markdown file.

```md
::figure{src="../../assets/layout-light.svg" dark="../../assets/layout-dark.svg" alt="Folders of a docsp project" caption="Folders of one project."}
```

::figure{src="../../assets/layout-light.svg" dark="../../assets/layout-dark.svg" alt="Folders of a docsp project" caption="Folders of one project."}

| Attribute | Required | Value |
|---|---|---|
| `src` | yes | Image for light mode, or for both modes without `dark`. |
| `dark` | no | Image for dark mode. |
| `alt` | no | Text alternative. Defaults to the label in brackets. |
| `caption` | no | Caption under the image. Defaults to the label in brackets. |
| `width`, `height` | no | Intrinsic size, to reserve space before the image loads. |

`::figure[Folders of a docsp project]{src="..."}` uses the label as both `alt` and `caption`.

## FAQ

`:::faq` turns each `###` heading into a question you can expand; the content up to the next heading is the answer.
`:::faq{open}` expands the first answer.

```md
:::faq{open}
### Can I use my own domain?
Yes. Serve the site at the root of the domain.

### Does search need a server?
No. The index is static files in `dist/pagefind/`.
:::
```

:::faq{open}
### Can I use my own domain?
Yes. Serve the site at the root of the domain.

### Does search need a server?
No. The index is static files in `dist/pagefind/`.
:::

## Glossary

`:::glossary` renders a list of `**Term**: definition` items. The definition is plain text.

```md
:::glossary
- **Section**: a tab of a project, and a folder of its pages.
- **Locale**: a language of the content, such as `en` or `pt-BR`.
:::
```

:::glossary
- **Section**: a tab of a project, and a folder of its pages.
- **Locale**: a language of the content, such as en or pt-BR.
:::

## Inline elements

Inline directives sit in running text.

- `:kbd[Ctrl]` is a key: press :kbd[Ctrl] + :kbd[K] to search.
- `:ui[Settings > Channels > Email]` is a path through the interface, with `>` between the parts: open
  :ui[Settings > Channels > Email].
- `:badge[Beta]{tone="info"}` is a badge: :badge[Beta]{tone="info"}. Tones are `ok`, `warn`, `err`, `info` and `neu`
  (the default).

## Tables

Tables are GitHub Flavored Markdown. docsp wraps each one in a bordered frame that scrolls sideways on narrow screens
and can be reached with the keyboard.

```md
| Plan | Jobs per month |
|---|---|
| Free | 10,000 |
| Team | 1,000,000 |
```

| Plan | Jobs per month |
|---|---|
| Free | 10,000 |
| Team | 1,000,000 |

:::warning[Keep directives and relative links out of tables.]
docsp does not process the content of table cells: an inline directive in a cell renders as plain text in a block,
and a relative link to a Markdown file is not turned into a page URL. Use absolute links (`/rocket/guides/quickstart/`)
in tables, or move the link to the text around the table.
:::

## Code from the source tree

`::snippet` shows lines of a file from the project's source checkout, with every name linked to the symbol a compiler
resolved. It needs a `symbols` block in `project.json`; without one, the build fails.

```md
::snippet{file="src/ffi.rs" lines="140-170"}
::snippet{file="src/ffi.rs" region="bump" title="The C entry point"}
```

| Attribute | Value |
|---|---|
| `file` | Path relative to the top folder of the source checkout. |
| `lines` | A line or a range, `12` or `12-40`. |
| `region` | The lines between a `docsp:region <name>` comment and the matching `docsp:endregion` comment. Regions nest. |
| `title` | Header of the block. Defaults to the file path. |

This site has no symbol index, so it shows no live snippet. The `spark` project of the example site in the docsp
repository has one: `examples/site/spark/docs/en/guides/counter.md`. See [Symbol index](../features/symbols.md).
