Callouts

The high bars get slippery, and Pango learned that the hard way. The first thing he ever wrote down was a warning, and he refused to bury it in a paragraph where a sleepy climber would skim straight past it. He wanted it loud. That is what a callout is for: pulling one important thing out of the flow so the eye cannot miss it.

Admonitions

Open a callout with three exclamation marks, a type, and an optional quoted title. Indent the body four spaces; everything indented under the opener belongs to the callout.

!!! warning "Chalk up first"    The high bars get slippery after the 1,000th ant.

Drop the title and the type's own name becomes the heading:

!!! note    Scales are self-cleaning. Please do not polish the pangolin.

The six types

Pick by what you mean, not by which colour you like. Readers (and screen readers) learn the meanings fast, so using danger for a mild aside just cries wolf.

!!! note    Neutral aside. Context the reader may want, but can live without.!!! info    Background worth knowing. A little more weight than a note.!!! tip    A shortcut, a better way, a thing Pango wishes he'd known sooner.!!! check    Something is confirmed working, finished, or verified. Same green tint as    `tip`, but the check icon reads as "yes, this is the right thing."!!! warning    Proceed carefully. Something here bites if you ignore it.!!! danger    Stop and read. Real consequences: data loss, broken systems, lost claws.

Rich bodies

A callout body is full Markdown. Lists, code, tables, even other callouts all work, as long as they stay indented under the opener.

!!! danger "Do not unroll a pangolin"    Do **not** unroll a curled pangolin. It can wait you out for hours, and it    will:    - ignore you completely    - win    ```bash    # the only correct move    leave-some-ants && back-away-slowly    ```

# the only correct moveleave-some-ants && back-away-slowly

Collapsible hatches

Some equipment only opens when Pango pokes it. Swap the !!! for ??? and the callout becomes collapsible, closed by default, so optional detail stays out of the way until a reader wants it.

??? note "What's behind the loose scale?"    A spare snack and a folded map of every air vent. Standard pangolin    contingency planning.

Add a + (???+) to start it open. Same collapsible behaviour, but the reader sees the content first and can fold it away.

???+ warning "Read before the high bars"    Chalk first. The fall is short but the somersault is involuntary.

Reach for a hatch when the content is genuinely optional: a long aside, a troubleshooting dump, a "why does this work" tangent. For a one-liner that everyone should read, a plain !!! callout is better; never hide the important thing behind a click.

Nesting

Callouts nest inside each other and inside other constructs. Keep adding four spaces of indentation per level.

!!! info "Open the hatch"    Some intro, then a collapsible inside the callout:    ??? tip "Click to expand"        Hidden tip content, two levels deep.

A typo degrades gracefully

Write a type docolin doesn't know and the callout falls back to a neutral box instead of vanishing, so the mistake surfaces where you can see it.

!!! mistery "Not a real type"    `mistery` isn't a type, so this renders as a plain box. Spot the typo,    fix it to `mystery`... which also isn't a type. Use one of the six.

Gotchas

• Four spaces, always. The body must be indented four spaces under the opener. Three spaces, or a tab that isn't four wide, and the line falls out of the callout.
• A blank line between callouts keeps two stacked callouts from merging. (You can see the gaps in the six-types example above.)
• Don't decorate. A page where every second paragraph is a callout has no callouts, just loud paragraphs. Save them for the things a reader truly must not miss.

See also

• Cards can be typed with the same six colours, for when the highlight is a whole linked panel rather than a line of prose.
• Steps covers the accordion, a close cousin of the collapsible hatch for grouped question-and-answer content.