What are GitHub Markdown callouts?

GitHub Markdown callouts, also known as alerts, are visual blocks that highlight critical information in READMEs or issues. You start a blockquote line with > [!NOTE] (or TIP, IMPORTANT, WARNING, CAUTION) and they render as distinctly colored boxes with icons.

Which alert types does GitHub support?

GitHub natively supports five alert variants: NOTE (blue), TIP (green), IMPORTANT (purple), WARNING (yellow), and CAUTION (red). Each is designed to convey a specific level of urgency or advice.

Are GitHub callouts standard Markdown?

No, they are a GitHub-specific extension. Obsidian uses a similar syntax with more types, but platforms like Docusaurus, GitLab, and MkDocs use entirely different formats. In unsupported parsers, they degrade to standard blockquotes.

How do I add line breaks in a Markdown callout?

Paragraph text without the blockquote prefix continues lazily, but blank lines, code fences, and lists need the prefix to stay inside the alert. Use a line with only the prefix character to separate paragraphs inside an alert.

GitHub Markdown Alerts: Syntax, Types and Common Mistakes

Documentation is the front door to any open-source or commercial software project. While standard Markdown provides the foundational structure for READMEs, GitHub introduced Markdown alerts (callouts) to help developers visually highlight critical information—such as deprecation notices, security warnings, or configuration tips.

However, formatting these callouts correctly, especially when nesting code blocks or lists within them, frequently leads to broken rendering.

This guide explores the underlying syntax of GitHub Markdown callouts, common structural pitfalls, and how to automate their creation safely using client-side tools.

The Standard GitHub Alert Syntax

GitHub Flavored Markdown (GFM) leverages standard blockquote syntax combined with a specific bracketed keyword to trigger the alert component.

To create an alert, you start the line with the blockquote symbol (>), followed by a space, and then the alert type enclosed in brackets with an exclamation mark ([!TYPE], as detailed in GitHub Docs: Alerts).

> [!NOTE]
> This is a standard GitHub note alert.

The 5 Native Callout Archetypes

GitHub rigidly enforces five specific alert types (see the official list). Using any other keyword will cause the block to render as a standard, unstyled blockquote.

Alert Type	Keyword	Primary Use Case	Visual Indicator
Note	`[!NOTE]`	General information or contextual details.	Blue, Info Icon
Tip	`[!TIP]`	Best practices, shortcuts, or optimization advice.	Green, Lightbulb Icon
Important	`[!IMPORTANT]`	Critical information necessary for the software to function.	Purple, Message Icon
Warning	`[!WARNING]`	Time-sensitive or potentially disruptive information.	Yellow, Triangle Icon
Caution	`[!CAUTION]`	High-risk actions that cause data loss or security issues.	Red, Octagon Icon

The Friction: Broken Nesting and Formatting Constraints

While a single-line alert is trivial to write, documentation often requires complex nested structures. Developers frequently encounter rendering failures when attempting to insert code blocks, lists, or multi-paragraph text inside a callout. (The failure cases below were verified by rendering them directly with GitHub’s own Markdown API.)

1. Breaking the Alert Syntax

A frequent mistake is attempting to add content on the same line as the alert marker, which turns it into a plain blockquote instead of an alert.

Incorrect Syntax (Renders as plain blockquote):

> [!WARNING] Do not execute this command as root.
> It will permanently delete the partition.

Correct Syntax:

> [!WARNING]
> Do not execute this command as root.
> It will permanently delete the partition.

Another common mistake is placing an alert inside a nested structure like a list or another blockquote. GitHub requires alerts to be at the top level.

Incorrect Syntax (Nested alert fails):

* Step 1: Initialize the database.
  > [!NOTE]
  > This might take several minutes.

To fix this, move the alert out of the list to the top level.

2. Dropping Content from the Alert

When embedding complex elements like code blocks or lists, failing to prefix lines with the blockquote symbol causes them to fall out of the colored box.

Here are the rules to remember when nesting content:

Code fences and lists: Lines without > drop out of the alert and render outside it.
Blank lines: A blank line without > ends the alert completely. Subsequent lines starting with > become a separate plain blockquote.
Spaces and types: A space inside the brackets (e.g., > [! NOTE]) or an unknown type (e.g., > [!DANGER]) will render as a plain blockquote.

Prefix every line, including the fences and the blank lines:

> [!TIP]
> Build with:
>
> ```bash
> npm run build
> ```
>
> Then deploy.

Client-Side Callout Generation

To avoid formatting errors, you can use the Markdown Callouts Tool to safely construct complex alerts instantly in your browser without sending your proprietary documentation to remote servers.

The tool supports formats for GitHub, GitLab, Obsidian, MkDocs, and Docusaurus. For GitHub, it supports note, tip, and warning types, plus it maps info to NOTE and danger to CAUTION. Simply paste your raw content (including code blocks), and the tool automatically prefixes every line with the blockquote marker so everything stays perfectly contained.

Implementing Pre-Flight Checks for Markdown

Before pushing documentation to your main branch, verify your callouts with this quick checklist:

Check Keyword Casing: Uppercase is the documented convention, but lowercase also works on GitHub.
Check Line Prefixes: Confirm every line within the alert boundary begins with > .
Prefix Code Fences: If your callout contains code blocks, ensure the triple backticks are also prefixed with > .
Fallback Degradation: Remember that parsers without alert support render a plain blockquote showing [!TYPE]. Ensure the text remains readable.