Markdown Blockquotes and Callouts: Syntax, Nesting, and When They Break

Quick answer

A Markdown blockquote is a line that starts with >. A callout — also called an alert or admonition — is that same blockquote with a label like [!NOTE] on its first line. Every callout is a blockquote underneath, and that's what keeps it readable even where the styling isn't supported.

Blockquotes are one of the plainest parts of Markdown. No closing tag, no nesting rules beyond repeating a character, nothing that breaks if you open the file in a different app later. That's part of why they're worth knowing well if you keep notes in a plain-text note-taking system — a blockquote written today reads the same in any editor five years from now.

Below: writing basic and nested markdown blockquotes, adding GitHub-style callouts on top of them, and the handful of formatting mistakes that quietly break both.

Step-by-step

Writing a basic markdown blockquote

Start a line with >, then a space, then your text. Markdown's original syntax treats this the same way email clients treat quoted replies — familiar if you've ever quoted a message before responding to it.

> Plain text outlasts almost every proprietary format.

The space after > is optional. CommonMark renders >text and > text the same way. And if you're hard-wrapping a paragraph across several lines, Markdown lets you put > before only the first one and still treats the whole paragraph as quoted.

Nesting blockquotes

Add another > to nest one level deeper:

> A first-level quote.
> > A second-level quote inside it.
> Back to the first level.

Each level needs its own marker on every line it covers. Blockquotes aren't limited to plain sentences, either — they can hold headings, lists, and fenced code blocks, which is what makes them useful as containers for asides and examples rather than just quoted prose.

Adding a GitHub-style callout

A callout is a blockquote whose first line is a bracketed type. GitHub's writing docs define five: NOTE, TIP, IMPORTANT, WARNING, and CAUTION.

> [!NOTE]
> This only renders as a styled callout on platforms that support the extension.

GitHub's own guidance is to use these sparingly — one or two per document — and never to nest an alert inside a list or another blockquote. The same restraint holds anywhere you use them. A callout on every paragraph stops meaning anything.

Blockquote syntax shows up elsewhere in a Markdown document too, the same way it shows up around links and images — one more piece of the small, composable syntax Markdown is built from.

Common problems and fixes

• A multi-paragraph quote splits into two. CommonMark requires `>` on blank lines inside a blockquote. A bare blank line — one with no > at all — ends the quote right there, and whatever follows starts a new block instead of continuing it.
• The blockquote turned into a code block. A > marker can carry 0-3 spaces of leading indentation. Four or more spaces triggers a code block instead, so one stray extra space before > is enough to break the quote.
• A `[!NOTE]` tag shows up as plain text instead of a styled box. That's expected, not broken. Callouts are a GitHub Flavored Markdown extension, not part of core CommonMark, so a plain-text viewer or a non-GFM renderer just shows the literal [!NOTE] line inside an ordinary blockquote. Run into other characters rendering oddly? Escaping special characters in Markdown covers the related backslash rules.
• A nested quote or callout doesn't nest the way you expected. GitHub's alerts specifically can't nest inside another blockquote or a list item. If you need that structure, a plain nested blockquote — without the [!TYPE] tag — is the safer choice.

Be honest about the trade-off. Callouts look better on platforms that render them. But a plain blockquote is the one piece of this syntax you can count on to look the same everywhere.

Doing this with Carets

Blockquotes and callouts are still just plain text, which is exactly what Carets is built around. It's a native, fast editor rather than a web wrapper, so writing a > line or a [!NOTE] block doesn't mean waiting on a heavy app to catch up — you type it and move on.

Markdown and plain text live in the same editor here, so a blockquote you write in a note reads exactly the same if you copy it into a README or a code comment later. Files, projects, and tags keep the notes, snippets, and drafts where you actually used blockquotes and callouts organized instead of scattered across apps. And because your files stay plain text the whole time, a callout you write today opens correctly in any other Markdown tool later — nothing proprietary to lose.

If Markdown syntax is a recurring question for you, the same habits carry over from keeping long documents navigable to the small details covered here.

Carets is available on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

What's the difference between a blockquote and a callout in Markdown?

A blockquote is core Markdown syntax — a > at the start of a line. A callout, also called an alert or admonition, is a platform-specific extension built on top of blockquote syntax, using a tag like [!NOTE] on the first line to add a label and styling. Every callout is technically a blockquote; not every blockquote is a callout.

Do callouts render correctly in plain-text editors that don't support them?

Yes, gracefully. Since a callout is just a blockquote with a [!TYPE]-style tag on the first line, a plain-text or CommonMark-only renderer that doesn't recognize the extension still shows a normal quoted block with the tag as visible text — it degrades to readable plain text instead of breaking.

How do I nest a blockquote inside another blockquote?

Stack the > marker once per level: a single > for the first level, > > for a quote nested inside it, and so on. Each level of nesting needs its own leading marker on every line that belongs to it.

Why did my multi-paragraph blockquote break into two separate quotes?

CommonMark requires a > on blank lines that fall inside a blockquote. If you leave a bare blank line between two paragraphs you meant to keep in the same quote, the parser ends the blockquote there and starts a new block after it — add > to that blank line to keep them together.

Which Markdown flavors support GitHub-style alert callouts?

GitHub's five alert types — NOTE, TIP, IMPORTANT, WARNING, and CAUTION — are a GitHub Flavored Markdown extension, not part of the core CommonMark spec. Other renderers may support similar callout syntax with different keywords, so check the target platform's docs before relying on a specific tag rendering as a styled box.