# Blockquotes

Prefix lines with `>`. Separate paragraphs inside a quote with a `>` on its own line.

~~~code-preview example
```md
> A single-line quote.

> First paragraph of a quote.
>
> Second paragraph, still quoted.
```
```md
> A single-line quote.

> First paragraph of a quote.
>
> Second paragraph, still quoted.
```
~~~

Blockquotes can contain other Markdown — lists, code, even nested quotes (prefix with
`> >`).

## Fenced (multi-paragraph) blockquotes

For a long quote with several paragraphs, prefixing every line with `>` is tedious.
Fence the whole quote with `>>>` instead — everything between the markers is quoted:

~~~code-preview example
```md
>>>
First paragraph of the quote.

Second paragraph — no `>` on any line.
>>>
```
```md
>>>
First paragraph of the quote.

Second paragraph — no `>` on any line.
>>>
```
~~~

## Callouts

A plain blockquote stays neutral. For a coloured, labelled box (note / tip / warning
/ …), use a **callout** — a blockquote whose first line is a GitHub-style `[!TYPE]`
alert marker. (A **[directive](directives.md)** like `:::tip` is an interchangeable
alternative.)

~~~code-preview example
```md
> [!NOTE]
> Useful information the reader should know.

> [!WARNING]
> Something that needs attention.
```
```md
> [!NOTE]
> Useful information the reader should know.

> [!WARNING]
> Something that needs attention.
```
~~~

The `[!TYPE]` marker must be **uppercase and alone on the first line**; anything else
renders as a plain blockquote. A callout can hold multiple paragraphs, lists, and code
— just keep them inside the `>` quote.

The five types, each with its own colour — the source, then how it renders:

### Note

Background or context the reader should absorb even when skimming — the fact still
matters if they skip it, so it earns a box rather than a plain sentence.

~~~code-preview example
```md
> [!NOTE]
> The compiled book works fully offline — no network access is needed to read it.
```
```md
> [!NOTE]
> The compiled book works fully offline — no network access is needed to read it.
```
~~~

### Tip

Optional advice: a shortcut, a better habit, a nicer way to do the same thing.
Nothing breaks if the reader ignores it.

~~~code-preview example
```md
> [!TIP]
> Name files after their page ids — links then read like the table of contents.
```
```md
> [!TIP]
> Name files after their page ids — links then read like the table of contents.
```
~~~

### Important

Information the reader *needs* for the task at hand to succeed — skipping it means
something won't work, even though nothing dangerous happens.

~~~code-preview example
```md
> [!IMPORTANT]
> Every page needs a unique id — two files can't share one.
```
```md
> [!IMPORTANT]
> Every page needs a unique id — two files can't share one.
```
~~~

### Warning

Something that demands attention *before* the reader acts — a common trap, a
surprising behavior, a step that's easy to get wrong.

~~~code-preview example
```md
> [!WARNING]
> Raw HTML is escaped, not rendered — `<b>bold</b>` shows up as literal text.
```
```md
> [!WARNING]
> Raw HTML is escaped, not rendered — `<b>bold</b>` shows up as literal text.
```
~~~

### Caution

Consequences: actions that are destructive, irreversible, or costly to undo. The
strongest signal — save it for cases where acting wrongly does real damage.

~~~code-preview example
```md
> [!CAUTION]
> `khb pack` starts from a clean slate — docsets already in the output directory
> are removed before the new ones are copied in.
```
```md
> [!CAUTION]
> `khb pack` starts from a clean slate — docsets already in the output directory
> are removed before the new ones are copied in.
```
~~~