Markdown blockquotes: quoting, nesting and alerts

Multi-line quotes and lazy continuation

Every line of a multi-line quote should carry its own marker:

> The best way to get the right answer on the internet
> is not to ask a question. It is to post the wrong answer.

Lazy continuation

Markdown lets you get away with less. When a quoted paragraph runs onto the next line, that line joins the quote even with no marker on it:

> The best way to get the right answer on the internet
is not to ask a question. It is to post the wrong answer.

Both versions render the same. This is lazy continuation. It exists because Markdown was written for people who wrap paragraphs by hand in a plain text editor. It applies only to the later lines of a paragraph that is already inside the quote.

Why being explicit is safer

Lazy continuation stops working the moment the unmarked line could start a block of its own. A bullet, a heading, a code fence or a table row escapes the quote with no warning at all:

> Keep pull requests small.
- Small changes get reviewed faster.

The first line is a quote. The second is an ordinary list outside it, and the raw text gives no hint of the split. Worse, any editor that re-wraps the paragraph can move the break and change the result.

Tip: Put a > on every line and this whole class of bug disappears. It is the same habit that keeps nested bullets stable in the lists reference: be explicit, and the parser has nothing to guess.

Blank lines split one quote into two

A blank line ends a blockquote. What looks like a single quote with two paragraphs is really two separate quotes:

> The first paragraph of the quotation.

> The second paragraph of the quotation.

You get two <blockquote> elements with a visible gap between them. On GitHub that is two grey panels instead of one.

The bare marker keeps a quote running

Quote the blank line as well. Write a > with nothing after it:

> The first paragraph of the quotation.
>
> The second paragraph of the same quotation.

That one character decides whether you get one quote or two. It also answers most "why is there a gap in my quote" questions.

The same marker separates any two blocks

Inside a quote, a bare > does the job that a blank line does in ordinary Markdown. Use it between:

• two paragraphs of one quotation
• a heading and the paragraph under it
• a paragraph and the list that follows
• a paragraph and an opening code fence

What you can put inside a quote

A blockquote holds any block content: paragraphs, headings, lists, code fences, tables, images, even other quotes. Two rules cover all of it.

1. Every line of that content needs the > marker, including lines that look empty.
2. Separate blocks with a bare >, never with a real blank line.

> ### Release checklist
>
> 1. Tag the release
> 2. Publish the notes
>
> ```bash
> git tag -s v2.1.0
> ```
>
> Both fences need the marker, not just the code.

Indentation inside a quote is measured after the marker is stripped, so a nested list behaves exactly as it does outside a quote. The lists reference has the space counts, and the code blocks reference has the fence rules.

Every block, and what to watch for

Watch out: a table inside a quote gets the quote's width, not the page's, so columns crush together fast. The tables reference covers when to pull one out into a section of its own.

Attribution lines

Markdown has no attribution syntax. Every convention below is a community habit rather than a rule. The most common one is a dash and a name on the last line of the quote:

> Simplicity is the ultimate sophistication.
>
> - Leonardo da Vinci

Print sets that leading dash as a long dash. In a source file a plain hyphen is safer. It survives copying between editors, and it never turns into a mangled character in a file saved with the wrong encoding.

Why the name turns into a bullet point

A hyphen followed by a space is list syntax, so the example above renders the name as a single bullet. Some themes make that look deliberate. Others make it look broken.

Three ways to keep it as plain text

• Escape the hyphen with a backslash, which keeps the dash and drops the bullet.
• Set the name in italics, which reads as a note rather than a list item.
• Use a nested quote, which separates the source from the words themselves.

> Simplicity is the ultimate sophistication.
>
> \- Leonardo da Vinci
>
> *Leonardo da Vinci, attributed*

The nested-quote version reads as a note about the quotation rather than part of it:

> Simplicity is the ultimate sophistication.
>
> > Leonardo da Vinci, widely attributed

Where inline HTML is allowed, <cite> gives you real semantics. Where it is not, the italic form from the bold and italic reference gets you most of the way there.

GitHub alerts and Obsidian callouts

GitHub added alerts in late 2023, built straight on blockquote syntax. The first line of the quote is a keyword in square brackets with a leading exclamation mark. The body follows on the next line:

> [!NOTE]
> Useful information a reader should not skip.

> [!WARNING]
> Something that could cause a problem if ignored.

The three rules GitHub checks

1. The keyword is uppercase: [!NOTE] works, [!note] does not.
2. It sits alone on the first line of the quote, with the text below it.
3. One quote holds one alert, and nested alerts are not supported.

Get all three right and GitHub draws a coloured border, an icon and a bold label. Get one wrong and you get a plain quote with visible brackets. The rest of the dialect is in the GitHub Flavored Markdown reference.

What happens on every other renderer

Alerts degrade rather than break. A renderer that has never heard of them sees an ordinary blockquote whose first line is the literal text [!NOTE]. The content stays readable, with one stray bracketed word on top. That trade-off is exactly why the syntax was built on quotes.

Obsidian callouts go further

Obsidian callouts start from the same base syntax and add four things:

• a much longer keyword list, including [!BUG] and [!EXAMPLE]
• lowercase keywords, so [!tip] is fine
• an optional custom title on the same line
• folding, with a trailing + or -

> [!tip] Faster than you think
> Callout titles are optional.

> [!warning]- Folded by default
> The minus sign starts this one collapsed.

The table below is the full keyword list, with the platforms that draw each one as a real callout.

Every keyword, and where it works

Tip: Pick the keyword by the risk to the reader, not by the colour you like. [!WARNING] is for a step that can break something, [!NOTE] for context, [!TIP] for advice they can skip. Four alerts in a row teach people to skip all four.

Common mistakes and their fixes

Five failures cover nearly every broken quote, and each one has a one-line fix:

1. No blank line before the quote, so the marker gets swallowed by the paragraph above.
2. A blank line where a bare > belongs, which splits one quote into two.
3. A list or fence that loses its marker and drags the rest of the block out of the quote.
4. An alert keyword in lower case, or with body text beside it on the same line.
5. Trailing spaces on a quoted line, which force a hard break and leave ragged short lines.

Fixing the two blank-line mistakes

CommonMark and GitHub let a quote interrupt a paragraph. Python-Markdown, which powers MkDocs, does not, and neither do Markdown.pl or many wikis. They print a literal > instead. Broken, then fixed:

Here is what the style guide says:
> Prefer short sentences.

Here is what the style guide says:

> Prefer short sentences.

The second mistake is the mirror image. A real blank line inside the quote gives you two quotes with a gap. Broken, then fixed:

> First paragraph.

> Second paragraph.

> First paragraph.
>
> Second paragraph.

Fixing a marker that goes missing

An unmarked line breaks out of the quote, and everything after it goes too. Broken, then fixed:

> Checklist:
> - Tag the release
- Publish the notes

> Checklist:
>
> - Tag the release
> - Publish the notes

Fixing an alert that renders as a plain quote

GitHub matches uppercase keywords on their own line only. Both of these fail, and both leave visible brackets:

> [!note] Rotate the signing key
> [!NOTE] Rotate the signing key

> [!NOTE]
> Rotate the signing key every 90 days.

Debugging anything else

The routine is the same everywhere in Markdown. Paste the quote into the editor and remove lines until it renders. The last line you removed is the culprit, and it is nearly always a missing marker or a stray blank line.

Blank lines carry a lot of meaning in this format, and what Markdown is for explains why. The cheat sheet keeps every quote form on one page, the complete guide puts quotes next to every other element, and the headings and footnotes references cover what people most often pair with a quotation.