Markdown Warning Box Syntax Tutorial

What is a Markdown Warning Box

When writing technical documentation, some content needs to stand out — things like "this operation is irreversible," "this API is deprecated," or "back up your data before proceeding." Regular paragraphs are easy for readers to skim past, but wrapping that text in a colored box with an icon makes a real difference.

That's what a Markdown warning box is for.

Here's the important caveat: native Markdown doesn't have a "warning box" syntax element. The CommonMark spec only defines basic structures like headings, lists, blockquotes, and code blocks. Warning boxes are platform-specific extensions built on top of blockquotes, and both the syntax and rendering vary by platform.

This article covers the warning box syntax across all major platforms. Just find the one you're using and copy the code.

GitHub Warning Box: The [!WARNING] Syntax

If you write documentation primarily on GitHub — READMEs, Issues, PR descriptions, Discussions — this is the most straightforward approach. GitHub officially launched its Alert syntax in December 2023, and the WARNING type is specifically designed for displaying warnings.

Basic Syntax

The syntax is simple. Start a blockquote with > [!WARNING], then write the content on the following lines prefixed with >:

> [!WARNING]
> This deletion cannot be undone. Please confirm before proceeding.

This renders as an orange callout box with a warning icon. Since it's built on blockquote syntax, even on platforms that don't support Alerts, the content won't be lost — it'll just render as a plain blockquote.

Multi-line Content

When your warning has multiple lines, each line must start with >:

> [!WARNING]
> This version has the following known issues:
> 1. Large file uploads may time out
> 2. Safari browser layout misalignment
> 3. Export functionality is temporarily unavailable

I once wrote migration docs for a project and forgot the > on one line in the middle. That paragraph ended up outside the warning box, and a reader reported it as a formatting issue. Took me a while to track down. So when writing multi-line warnings, double-check every line.

Using Markdown Formatting Inside Warnings

Common Markdown formatting works inside warning boxes — bold, inline code, and links are all fine:

> [!WARNING]
> The `getUser()` method is deprecated in `v2.0`. Migrate to `fetchUser()` instead.
> See the [migration guide](https://example.com/migration) for details.

Lists and code blocks inside warnings can be a bit inconsistent with indentation, especially across different editor previews. If possible, keep warning content concise and put complex formatting in the body text.

Warning Box Syntax Across Platforms

GitHub's [!WARNING] isn't the only way to create a warning box. Different platforms have their own syntax. Here's a side-by-side comparison.

GitHub

> [!WARNING]
> Warning content goes here.

Supports 5 types: NOTE, TIP, IMPORTANT, WARNING, CAUTION. WARNING renders as an orange box.

Obsidian

> [!warning] Custom Title
> Warning content goes here.

Obsidian's callout syntax is nearly identical to GitHub's, but it supports custom titles (written directly after the brackets) and 12 built-in types. Obsidian also supports collapsible callouts:

> [!warning]- Click to expand
> This content is collapsed by default.

MkDocs (Material Theme)

!!! warning "Attention"
    Warning content goes here, must be indented 4 spaces.

MkDocs uses !!! markers. The type name can be followed by a quoted title. Content must be indented 4 spaces — this is where most beginners mess up. If the indentation is wrong, the content won't be recognized as part of the admonition.

Docusaurus

:::warning
Warning content goes here.
:::

Docusaurus wraps content with triple colons — the simplest syntax of all. Custom titles use square brackets:

:::warning[Data Loss Risk]
Warning content goes here.
:::

MyST / Jupyter Book

```{warning}
Warning content goes here.

MyST uses directive syntax similar to code blocks. Supports `:class: dropdown` for collapsible warnings.

### Quarto

```markdown
::: {.callout-warning title="Custom Title"}
Warning content goes here.
:::

Quarto uses Pandoc's fenced div syntax with the .callout-warning class.

Platform Comparison Table

PlatformSyntaxCustom TitleCollapsibleFallback
GitHub> [!WARNING]NoNoPlain blockquote
Obsidian> [!warning]YesYesPlain blockquote
MkDocs!!! warningYesYes (???)Not rendered
Docusaurus:::warningYesNoNot rendered
MyST```{warning}YesYesNot rendered
Quarto::: {.callout-warning}YesYesNot rendered

GitHub and Obsidian have the closest syntax — both extend blockquotes. This means migrating between the two platforms costs almost no effort. And on unsupported platforms, they degrade gracefully to plain blockquotes without losing content.

Fallback Methods for Unsupported Platforms

If your platform doesn't support the GitHub Alert syntax (like GitLab, Bitbucket, or standard Markdown editors), there are several workarounds to create warning-like effects.

Blockquote + Emoji + Bold Text

The most universal approach — works in every Markdown environment:

> ⚠️ **Warning:** This deletion cannot be undone. Please confirm before proceeding.

This doesn't have a colored box or icon, but the ⚠️ emoji and bold text make it noticeably more prominent than a regular paragraph. If cross-platform compatibility is your priority, this is the safest choice.

Table Hack

Using a single-column table with emoji to simulate a bordered area:

| ⚠️ **Warning** |
|:---|
| This deletion cannot be undone |

This does render as a bordered box on GitHub. But it's semantically a table, not a warning, and you can't change colors or distinguish between severity levels.

HTML Approach

Embedding HTML with inline styles:

<div style="background: #fff3cd; padding: 12px; border-left: 4px solid #ffc107; border-radius: 4px;">
<strong>⚠️ Warning:</strong> This deletion cannot be undone.
</div>

This works fine on self-hosted documentation sites or blogs where you control the rendering. But here's the catch: GitHub strips style attributes for security. So on GitHub READMEs and Issues, the div renders but loses all styling.

If you just need a warning box on GitHub, use [!WARNING]. The HTML approach is better suited for custom documentation sites.

WARNING vs Other Alert Types

GitHub provides 5 alert types, and it's worth understanding when to use WARNING specifically:

TypeSemantic MeaningSeverityTypical Use Case
NOTESupplementary infoLow"This feature has a size limit"
TIPOptional suggestionLow"Try using the CLI approach"
IMPORTANTMust knowMedium"Python 3.10+ only"
WARNINGPotential riskMedium-High"This API is deprecated"
CAUTIONSevere consequencesHigh"Directly modifying production database"

The most common question is WARNING vs CAUTION. The distinction: WARNING means "be careful, this might cause issues" while CAUTION means "don't mess with this, the consequences are severe."

Example: "Make sure the branch is merged before deleting" fits WARNING. "Directly modifying the production database may cause service disruption" should use CAUTION.

My rule of thumb: WARNING covers most situations that need attention. Reserve CAUTION for truly irreversible actions. If a document is full of CAUTION boxes, readers will start ignoring them.

Writing Effective Warning Content

The syntax is just a few lines. What really matters is what you write inside the warning box.

Be specific. "Proceed with caution" is useless. A good warning tells readers the concrete consequence and the alternative: "Deletion is irreversible. To preserve data, run the backup command first (see Step 3)."

Place warnings before the action. Readers should see the warning before they encounter the dangerous operation. If you show rm -rf /data first and then say "this deletes everything" below it, it's too late.

Keep it brief. One or two sentences is ideal. If you need three paragraphs to explain the risk, that content probably belongs in the body text, with a short warning box before the action step as a reminder.

Don't overuse them. Three to five warnings per page is already a lot. More than that and readers develop banner blindness — they stop noticing them entirely.

FAQ

Why isn't my [!WARNING] rendering with styles?

The three most common reasons:

  1. [!WARNING] must be on its own line — content starts on the next line
  2. Content lines must have > at the very start — no spaces before >
  3. You're not on GitHub — GitLab, Bitbucket, and other platforms don't natively support this syntax

Can I customize the WARNING color and icon?

Not on GitHub. All five alert types have fixed colors and icons. If you need custom styling, use Obsidian (custom callouts via CSS) or MkDocs (override admonition styles via CSS).

Can I nest a warning box inside another box?

Not recommended. GitHub Alerts don't support nesting. Obsidian and MkDocs technically allow it, but beyond two levels the readability drops significantly.

How do I write a warning box on GitLab?

GitLab doesn't natively support the [!WARNING] syntax. Use the blockquote + emoji fallback: > ⚠️ **Warning:** Your warning text here. GitLab has its own Markdown extensions, but nothing equivalent to GitHub's colored callout boxes.

References