[@layout]: ../docs.layout.md

# Callouts

A callout is a blockquote whose first line names its type. Use one to set a note, tip, or warning apart from the flow.

```md live
> [!tip] Keep it short
> One or two sentences, with **normal Markdown** inside.
```

> [!tip] Keep it short
> One or two sentences, with **normal Markdown** inside.

---

## Fold and nest supporting detail

Create `paths/hint.page.md` in an initialized project:

```md
# Try before opening the hint

> [!question]- Need a hint?
> Compare the lightest and darkest parts first.
>
> > [!tip] Check your result
> > Read the heading from across the room.
```

> [!question]- Need a hint?
> Compare the lightest and darkest parts first.
>
> > [!tip] Check your result
> > Read the heading from across the room.

Run `bun run dev` and open `/hint.page`. The hint starts closed; activate its
summary with Enter, Space, or a tap to reveal both the explanation and nested tip.
Change `-` to `+` to start it open. Both work in reading and Play; the disclosure
retains its native control behavior.

---

## Contract

| Syntax                 | Meaning                                                        |
| ---------------------- | -------------------------------------------------------------- |
| `> [!type]`            | Callout with the type name as its title                        |
| `> [!type] Title`      | Callout with an authored title                                 |
| `> [!type]+ Title`     | Foldable, open by default                                      |
| `> [!type]- Title`     | Foldable, closed by default                                    |
| `> > [!type]`          | Nested callout inside another callout's body                   |

Built-in types and their aliases:

| Type        | Aliases                 |
| ----------- | ----------------------- |
| `note`      |                         |
| `abstract`  | `summary`, `tldr`       |
| `info`      |                         |
| `todo`      |                         |
| `tip`       | `hint`, `important`     |
| `success`   | `check`, `done`         |
| `question`  | `help`, `faq`           |
| `warning`   | `caution`, `attention`  |
| `failure`   | `fail`, `missing`       |
| `danger`    | `error`                 |
| `bug`       |                         |
| `example`   |                         |
| `quote`     | `cite`                  |

## Notes

- Unknown types render with the `note` appearance and keep their own
  `data-callout` attribute for CSS.
- Foldable callouts render as native `<details>`, so they work without
  JavaScript.
- Lists, tasks, code fences, and links work inside a callout body.

## Related

- [Callouts demo](../../examples/callouts.demo.md) exercises every built-in type.