GitHub Alerts

GitHub alerts let you highlight important information using a familiar blockquote syntax. The starlight-github-alerts plugin converts them into styled Starlight asides automatically.

Alert types

GitHub defines five alert types. Each one maps to a Starlight aside variant:

GitHub Alert	Renders as Starlight	Appearance
[!NOTE]	note	Blue info box
[!TIP]	tip	Purple suggestion box
[!IMPORTANT]	caution	Yellow warning box
[!WARNING]	caution	Yellow warning box
[!CAUTION]	danger	Red danger box

Note that [!IMPORTANT] and [!WARNING] both render as the caution aside, while [!CAUTION] renders as the more severe danger aside.

Note → note

Note

Useful information that users should know, even when skimming content.

Tip → tip

Tip

Helpful advice for doing things better or more easily.

Important → caution

Caution

Key information users need to know to achieve their goal.

Warning → caution

Caution

Urgent info that needs immediate user attention to avoid problems.

Caution → danger

Danger

Advises about risks or negative outcomes of certain actions.

Syntax

The syntax mirrors what you’d write in a GitHub issue or PR:

> [!NOTE]
> Your note content here.

> [!TIP]
> Your tip content here.

Alerts with rich content

Alerts support full Markdown inside them:

Tip

You can use bold, italic, inline code, and even links like Starlight docs inside alerts.

• Bullet lists work too
• So do numbered lists

// Even code blocks
console.log("Hello from an alert!");

Customizing the mapping

The plugin accepts options to change which Starlight aside each alert type renders as. The defaults are:

starlightGitHubAlerts({
  types: {
    note: "note", // blue
    tip: "tip", // purple
    important: "caution", // yellow
    warning: "caution", // yellow
    caution: "danger", // red
  },
});

Each value can be 'note', 'tip', 'caution', or 'danger'.

When to use which

Note

Use Note for supplementary context that adds depth but isn’t critical to the main flow.

Tip

Use Tip for actionable shortcuts, best practices, or “pro tips” that save time.

Caution

Use Important for prerequisites, requirements, or key facts that affect outcomes.

Caution

Use Warning when skipping this information could cause errors or broken setups.

Danger

Use Caution when an action is destructive, irreversible, or has security implications.