GitHub Alerts

Created May 28, 2026Updated Jul 13, 2026Takeshi Takatsudo

Converts GitHub-style > [!NOTE] alert blockquotes into admonition markup.

The GitHub Alerts feature converts GitHub-style alert blockquotes — the > [!NOTE] syntax you see in README files — into the same admonition markup produced by the admonitions recipe (the directives map). This lets you author callouts with the familiar GitHub syntax and have them rendered identically to :::note-style directives.

Included in the standard preset

zudoDoc() enables GitHub Alerts. No separate configuration field is necessary:

// zfb.config.ts
import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";

export default defineConfig(
  zudoDoc({
    siteName: "My Docs",
  }),
);

Syntax

Prefix a blockquote with [!TYPE] on its first line (the type is matched case-insensitively):

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

Variants

Five alert types are supported. Each maps to an admonition variant:

Prefix	Variant
`[!NOTE]`	`note`
`[!TIP]`	`tip`
`[!IMPORTANT]`	`important`
`[!WARNING]`	`warning`
`[!CAUTION]`	`caution`

Package-provided components

zudo-doc registers the Important and Caution components, so all five alert variants render without project-side component registration. You can override any of these components through mdxExtras.

Live demo

All five variants are rendered live below:

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.

Emitted markup

The output is identical to the admonitions recipe (the directives map) — for example > [!NOTE] produces:

<div data-admonition="note" class="admonition admonition-note">
  <p class="admonition-title">…</p>
  <div class="admonition-body">…</div>
</div>

Notes

[!TYPE] is the only supported syntax. A trailing inline title like > [!NOTE] My Title is treated as a plain blockquote, not an alert.
Multiple paragraphs are supported — all body content lands inside the admonition.
GitHub Alerts and the admonitions recipe (the directives map) coexist: GitHub alerts are processed before the admonitions pass, so you can enable both at once.

View source on GitHub