# Docs components

The components an MDX page on the docs site can use by name, each shown working, with the lines that make it. Pages in docs/ are plain Markdown and don't need them.

Import the ones a page uses at the top of the `.mdx` file:

```mdx title="page.mdx"
import { Steps, Step, Callout } from "~/components/mdx";
```

## Steps

For a task done in order, on guides only. Each step's title is the instruction; its body says what happens.

1. **Open Settings → Machines and choose Add machine**

   The dialog shows an install line made for your Andon, and waits for the machine to connect.

2. **Run the install line in a terminal on that machine**

   A machine without a browser prints a link and a code instead.

```mdx
<Steps>
<Step title="Open Settings → Machines and choose Add machine">
The dialog shows an install line made for your Andon…
</Step>
</Steps>
```

## Callout

An aside in one of the board's four signal colours, so it means what it means on the board. There is no fifth.

> **Note:** Note.
>
> Extra context.

> **Tip:** Tip.
>
> A faster or better way.

> **Warning:** Warning.
>
> Something that will need you, amber like Needs you on the board.

> **Danger:** Danger.
>
> Data loss, or something you can't undo, red like a failed run.

```mdx
<Callout type="warning" title="It runs only while you are logged in.">
On a Mac that should take work around the clock, keep a user logged in.
</Callout>
```

## Tabs

Alternatives. The tab row is a real tab list: `←` and `→` move between tabs, `Home` and `End` jump to the ends. Choosing a tab opens the tab with the same label everywhere on the page. When each tab holds one code block, the tab row is the block's header and Copy copies the open tab.

**Has a browser**

```sh
$ curl -fsSL https://your-andon/install.sh | sh
✓ Enrolled as "Studio Mac"
```

**No browser**

```sh
$ curl -fsSL https://your-andon/install.sh | sh -s -- --no-browser
Open https://your-andon/approve and enter the code ABCD-1234
```

**Has a browser**

A tab can hold any content. This set switched along with the one above, because its labels match.

**No browser**

Pick **No browser** in either set and both follow.

```mdx
<Tabs label="Whether the machine has a browser">
<Tab label="Has a browser">

…a code block…

</Tab>
<Tab label="No browser">…</Tab>
</Tabs>
```

## Code blocks

Every fenced block gets a header with its file name (`title="…"`) or its language, and **Copy**. In a shell block,
lines starting with `$ ` are commands and the rest is output: Copy takes the commands without the `$ `, so what it copies
can be pasted and run. Placeholders the reader replaces, written `<your board>`, `<recipe-slug>` or `your-andon`, are
drawn in the accent colour.

```sh
$ andon doctor
✓ Signed in as Studio Mac
✓ Claude Code 2.1
$ andon policy approve <recipe-slug>
```

```json title="~/.config/andon/config.json"
{ "boardUrl": "https://your-andon" }
```

## Figure

A screenshot or an illustration in a feature pane, with its caption under it.

*Figure: The caption says what the reader is looking at.*

```mdx
<Figure caption="An item in Needs you.">
  ![Needs you, with one question waiting](./needs-you.png)
</Figure>
```

## FieldList

A reference page's fields: the name and its type on the left, what it does on the right. Under 640px wide the two stack.

- `permission-mode` (`plan | dontAsk | manual | acceptEdits | auto`): The most a run may use. A run that asks for more runs in this mode.
- `auto-update` (`on | off`): Whether the agent installs the board's signed build once a day.

```mdx
<FieldList>
  <Field name="auto-update" type="on | off">Whether the agent installs…</Field>
</FieldList>
```

## Chip and Kbd

Inline labels. A changelog entry's kind takes a signal colour; `order` numbers a list read in order, such as the models
Andon switches to; `label` is a plain tag. `⌘K`, `↵` and `esc` are keys.

Added Changed Fixed Docs

Claude Opus Claude Sonnet Codex

```mdx
<Chip kind="added">Added</Chip> <Chip kind="order" n={1}>Claude Opus</Chip> <Kbd>⌘K</Kbd>
```

## Previous and next

The two panes at the bottom of every page link the page before and after it in the sidebar. They come from the
sidebar's order, which is `docs/README.md`'s order, so a page needs nothing to get them.
