Skip to main content

Alerts

3 min readStableBeginner

An alert is a plain Markdown blockquote whose first text is a type marker like [!NOTE]. The remark plugin at lib/remark-github-alerts.mjs strips that marker, then prepends an icon and a bold label and tags the blockquote with a color class. Six types exist: NOTE, TIP, IMPORTANT, WARNING, CAUTION, and DANGER.

Quick Start

Start a blockquote with the marker and write the message on the same line.

ℹ️ NOTE Notes highlight information readers should notice while skimming.

app/features/components/alerts.mdx
Markdown
> [!NOTE] Notes highlight information readers should notice while skimming.

Adding Options

Swap the marker for a different type. Everything after it is ordinary Markdown, so bold, italics, inline code, and links keep working.

💡 TIP Press Cmd+K to search every page without leaving the keyboard.

📝 IMPORTANT Set ACCESS_MODE before you deploy. It decides whether the site asks for a password.

💡 TIP Bold, italics, inline code, and links all render inside the body.

app/features/components/alerts.mdx
Markdown
> [!TIP] Press `Cmd+K` to search every page without leaving the keyboard.
 
> [!IMPORTANT] Set `ACCESS_MODE` before you deploy. It decides whether the site
> asks for a password.
 
> [!TIP] **Bold**, _italics_, `inline code`, and
> [links](/features/components/badge) all render inside the body.

Advanced

Only the first paragraph carries the marker, so the rest of the blockquote can run as long as the warning needs. Escalate through WARNING, CAUTION, and DANGER when the risk gets worse.

⚠️ WARNING Be careful when you change environment variables.

Rotating JWT_SECRET invalidates every active session, and readers have to log in again.

⚡ CAUTION Deleting a page also drops its search records and its entry in related lists on other pages.

🚨 DANGER Running the reset script wipes the local database. There is no undo.

The match is strict about where the marker sits. Wrap it in emphasis, indent it behind a list, or lowercase it, and the blockquote renders as an ordinary quote with the marker text left in place:

[!NOTE] Bold around the marker means the first thing in the paragraph is no longer plain text, so nothing is stripped and no color is applied.

app/features/components/alerts.mdx
Markdown
> [!WARNING] Be careful when you change environment variables.
>
> Rotating `JWT_SECRET` invalidates every active session, and readers have to
> log in again.
 
> [!CAUTION] Deleting a page also drops its search records and its entry in
> `related` lists on other pages.
 
> [!DANGER] Running the reset script wipes the local database. There is no undo.
 
> **[!NOTE]** Bold around the marker means the first thing in the paragraph is
> no longer plain text, so nothing is stripped and no color is applied.
 
> [!note] Lowercase never matches either.

Options

[!TYPE]markerrequired

The alert type, written as the first text inside the blockquote. One of the six types below. Everything the marker matches, including the whitespace or line break after it, is removed before rendering.

bodymarkdown

Everything after the marker. Bold, italics, inline code, and links all work, and extra > paragraphs extend the alert.

Alert types

Each type sets the left border color, the tinted background, the icon, and the bold label printed ahead of your text.

[!NOTE]marker

Blue border and tint with an ℹ️ icon. Context the reader should notice while skimming, with no action attached.

[!TIP]marker

Green border and tint with a 💡 icon. A shortcut or a better approach.

[!IMPORTANT]marker

Purple border and tint with a 📝 icon. Something the reader has to know to finish the task.

[!WARNING]marker

Yellow border and tint with a ⚠️ icon. Skipping it causes problems later.

[!CAUTION]marker

Orange border and tint with a ⚡ icon. Risk of data loss or an unintended side effect.

[!DANGER]marker

Red border and tint with a 🚨 icon. Destructive and irreversible.

Syntax rules

marker caseuppercase

The plugin matches uppercase only. [!note] stays an ordinary blockquote.

marker linesame or next line

The marker can sit alone on the first line with the message starting on the next one, GitHub-style. The pattern swallows the line break along with the marker, so both forms render identically. Prettier's Markdown formatting in this repo pulls the message back up onto the marker line.

marker positionfirst text node

The marker has to be the first plain text of the blockquote's first paragraph. A blockquote that opens with a heading, a list, an image, or any emphasis around the marker never matches.

rendered markupblockquote

A matched blockquote gets class="github-alert alert-note" (or the matching type suffix) plus data-alert-type="note", so you can target one alert type from CSS or read the type back out of the DOM.

Related pages

Blockquotes

Was this page helpful?