GitHub Markdown Alerts and Callouts

Supported alert types

GitHub supports five alert labels for repository documentation. NOTE adds useful context without implying immediate action. TIP offers a practical suggestion that can save time. IMPORTANT highlights information required for a successful task. WARNING points to a possible problem or unwanted result. CAUTION signals a serious risk, such as data loss or an unsafe production change. Each alert begins with a blockquote marker, a space, and the label. The label must use the square brackets and exclamation mark shown in the syntax. Alert text follows on one or more blockquote lines. You can include ordinary Markdown inside the body, including links, inline code, and lists where the renderer permits it. Use one alert type per block so readers can scan the page quickly.

Write alerts that help readers act

A useful callout answers three questions: what is happening, who needs to care, and what action should follow. Place the alert beside the related instruction rather than collecting every warning at the top of a page. Use NOTE for background information, not hidden requirements. Use TIP for an optional shortcut. Reserve IMPORTANT for a required setting or dependency. Use WARNING when a command can change files, permissions, costs, or service behavior. Use CAUTION for irreversible operations or possible data loss. Keep the first sentence direct. State the consequence before adding an explanation. Avoid using alerts for every paragraph because repeated visual emphasis reduces their value. Review alerts when commands, APIs, or deployment procedures change.

Common syntax and rendering limits

The basic pattern is a blockquote with the alert label, followed by blockquoted content. Every line in a multi-line alert should normally retain the > marker so the renderer treats the content as one block. Do not replace the label with a heading, HTML comment, or custom color name. GitHub's supported alert syntax is a GitHub-specific Markdown extension, so another Markdown processor may show the text as an ordinary blockquote. Preview the file on GitHub before publishing instructions. Alerts also depend on the page surface and renderer version. If a page must work in several systems, provide the important instruction in normal prose as well, rather than relying only on color or an icon.

Working example

This example warns contributors before they run a command that changes generated files.

> [!WARNING]
> Run this command only after committing your current changes.
>
> The generator replaces files in the `docs/` directory.

GitHub renders a warning callout containing the instruction and the explanation. The inline code around `docs/` remains readable inside the alert.

Keep the warning close to the command it describes. Do not place critical recovery instructions only inside a colored callout.