Callouts

Callouts — admonitions, alerts, whatever you call them — are blockquotes with a colour, an icon and a label, used to mark content that a skimming reader should not miss.

The important decision here was not inventing a syntax. This site renders GitHub’s alert extension, which is the same syntax Bear uses. A note written in Bear pastes into a post and renders correctly, with nothing to translate. That is the whole point: the notes and the published site share one format.

The five standard types#

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Which renders as:

The distinction that actually matters when writing is warning versus caution. A warning is about the reader’s attention — something will go wrong if you skim past this. A caution is about the consequences of an action — this step can destroy data. If nothing bad happens by ignoring it, it is a note.

A plain blockquote stays a plain blockquote. Use one for actual quotation. Use pullquote only when the quote should become an editorial beat in the page, not just quoted evidence.

Pull Quotes#

pullquote sets a short line apart from the surrounding prose. It is useful for a memorable sentence, a representative dialogue fragment, or a line that should carry the rhythm of the article. It is not a severity marker, and it should not replace callouts.

{{< pullquote >}}
Predictable is a courtesy. A broken link is a broken promise.
{{< /pullquote >}}

Which renders as:

Custom titles#

Text after the type replaces the default label:

> [!IMPORTANT] Registration expires every three years
> Diarise the renewal.

Titles are localised when you don’t override them: a [!TIP] is Tip in English and Conseil in French, so the same file works in both languages without hardcoding.

Rich content#

Callouts take normal Markdown — lists, inline code, emphasis, links:

> [!NOTE]
> Three things worth knowing:
>
> - Lists work
> - So does `inline code`
> - And **emphasis**

The sixth type: archive#

archive is this site’s own, with no GitHub equivalent, so it stays a shortcode. It marks a page kept for the record rather than maintained — most of the macOS release pages carry one.

{{< callout type="archive" >}}
This page documents a release that Apple no longer supports.
{{< /callout >}}

Which renders as:

The shortcode still accepts every type, and danger is kept as an alias for caution so older posts keep working. For anything except archive, prefer the Markdown syntax — it survives being copied out of the site.

How it works#

A blockquote render hook at layouts/_default/_markup/render-blockquote.html inspects each blockquote, and hands anything carrying an alert marker to layouts/partials/callout.html. The shortcode calls that same partial, so the two entry points cannot drift into rendering differently.

Callouts signal severity. They are deliberately not used for pointing at other pages — that is a separate, quieter mechanism, covered in cross-references. A companion note styled like a warning teaches readers to ignore warnings.

Accessibility#

• The type is never colour-only: each callout carries a visible, localized text label — Note, Tip, Important, Warning, Caution, Archive note — rendered as real text before the body, and the icon beside it is aria-hidden="true" and purely decorative
• The container is a plain <div>, not role="alert" or role="status" — a callout is static page content, not a live announcement, so it takes no ARIA live role and interrupts nothing
• No element inside the callout takes focus or manages keys; links and code inside the body keep their own native behaviour
• Avoid a title override that removes the severity word — a custom title still needs to read as what it is (a warning, a note) rather than only match the surrounding colour