Alerts

An alert is a callout box: a colored panel with an icon and a heading, used to interrupt the reading flow for something the reader needs before they carry on. The Alert control on the editor toolbar is a dropdown of the five types, and picking one wraps the current block. This page is the format underneath it — the syntax an AI client writes, an importer produces, and a round-tripped page comes back as.

A basic alert

Wrap content between an opening ::: line naming the type and a closing ::: line:

:::note
This is a note.
:::

How it renders

The rendered structure is stable, and worth knowing if you are styling it:

<aside class="alert alert-note">
  <div class="heading">
    <i class="fa-icon"></i>
    <span class="description">Note</span>
  </div>
  <div class="content">
    <p>This is a note.</p>
  </div>
</aside>

Two hooks matter. The <aside> carries both alert and alert-<type>, so a rule can target all alerts or one type. And the icon element is emitted bare — <i class="fa-icon"> with no glyph class on it at all — which means the icon is chosen entirely in CSS, per type. That is why re-skinning alerts is a stylesheet job and never a markdown one; theming alerts has the selectors and the color tokens.

Write :::note, not ::: note

The opening fence is three or more colons followed immediately by the type name, with no space between them.

The closing fence must have the same number of colons as the opening one, on a line of its own. Both layers agree on that.

The five types

Each type has its own icon and color treatment, so the severity reads before the words do:

The set is closed on the site. Exactly five container types are registered in the site renderer, so a fence naming anything else is not an alert there at all — it falls through and renders as ordinary text. There is no extension point and no setting: a sixth type is a change to three files, not a configuration.

The editor is looser, and this is the one place worth knowing the difference. Its parser takes any word after the colons and stores it as the alert’s type; nothing checks that word against the five. So a :::custom fence that renders as a plain paragraph on your site comes back from the editor as a real alert node carrying type: "custom" — a panel with no color, no icon and no toolbar entry — and serializes out again as :::custom, unchanged and still inert on the site. Write only the five. Fidelity and Unsupported Syntax records the divergence alongside the others.

The default type is info, which is what an alert gets if something creates one without saying which kind it is.

Custom titles

Anything after the type on the opening line becomes the heading. With no title, the capitalized type name is used — which is where the “Note” in the first example came from.

:::tip Save yourself a redeploy
Changing a menu is a publish, not a build.
:::

How it renders

A short, specific title tells a reader whether the callout applies to them before they read the body. “Requires an administrator”, “Only on the free plan” and “Backup first” all do more work than “Warning”.

The title is inserted into the heading as plain text, so markdown inside it is not parsed — backticks in a title render as backticks. Put code in the body.

An alert inserted from the toolbar arrives with its title already set to the type’s own name, so it serializes as :::note Note rather than a bare :::note. The rendered heading is identical either way — the fallback and the explicit title produce the same words — so this is a spelling difference in the stored markdown, not a change to the page. The dialog above is where you replace it with something useful. Block types and settings covers the rest of that panel.

Content inside an alert

An alert holds block content: paragraphs, lists, tables, code fences, images. Use one more backtick on the outer fence than the inner one needs, so the code block inside does not close early:

:::info Install the CLI
Run this once per machine:

```bash
curl -fsSL https://app.leed.ai/install | bash

:::

### How it renders {data-id="fdu1l4nt"}

:::info Install the CLI {data-id="ub6rdzs1"}

Run this once per machine:

```bash
curl -fsSL https://app.leed.ai/install | bash

:::

Nesting

To put an alert inside an alert, give the outer one more colons. The inner fence’s three colons then cannot close the outer block.

::::tip Outer alert
Everything here belongs to the tip.

:::info
And this is a separate callout inside it.
:::
::::

How it renders

The editor counts for you, using 3 + the deepest nesting inside this alert: a plain alert is written with three colons, one containing another gets four, two levels deep gets five. That is why a :::: fence turns up in a round-tripped file you only wrote three colons in — nothing has gone wrong, the block simply grew something.

Attributes

Attributes go at the end of the opening line, after the title if there is one. Alerts use the permissive parser, so the shorthand forms work here — unlike the attribute line that a table or a blockquote reads, where only key="value" is accepted.

:::warning Check your quota {#quota-warning}
Content here.
:::

Page types can switch alerts off — on blogs only

Alerts are one of nine formatting features that can be turned off per page type, and they are off by default. The switch exists for posts-type page types alone: on a documentation or api page type it is inert on every surface — the API skips the check, the toolbar shows the control, and Settings does not render the toggle block at all. There is no way to disable alerts on a documentation set, and no hidden control to look for.

On a posts-type page type the gate covers API and MCP writes as well as the toolbar, and rejects with a 400 that names what it refused:

This page type does not allow: alerts. Allowed formatting features: code blocks.

Formatting by page type has the full list of switches and where they live.