Blockquotes and Rules

Basic Blockquotes

A > at the start of a line quotes it. The space after > is optional but conventional.

> This is a blockquote.

> This quote spans
> two source lines and renders
> as one paragraph.

Lazy continuation applies, so only the first line strictly needs the marker. It renders the same, but it is fragile: adding a block element later then requires the prefix, and linters flag it.

> This works because of lazy continuation
but this line has no marker and still joins the quote.

Two paragraphs inside one quote need a > on the blank line between them. Without it, the quote ends.

> First paragraph of the quote.
>
> Second paragraph of the same quote.

> First quote.

> A separate quote, because the blank line has no marker.

Nesting

Stack the markers. Each additional > adds a level.

> Level one.
>
> > Level two, nested.
> >
> > > Level three.
>
> Back to level one.

>> with no spaces works too, though the spaced form is easier to read in the source. Nesting is how quoted email replies and quote-of-a-quote citations are represented.

Blocks Inside a Quote

A quote can hold any block element as long as every line carries the marker, including blank lines and fence markers.

> ## A heading in a quote
>
> - a list item
> - another item
>
> 1. an ordered item
>
> | Column | Value |
> |--------|-------|
> | a      | 1     |
>
> Text with **bold** and `code`.

The failure people hit is a fenced code block inside a quote. Both the opening and closing fence lines need the > prefix. Drop it on the closer and the fence stays open, consuming the rest of the document.

Every line of a quoted code block, including the two fence
marker lines, needs a leading greater-than sign.

A quote inside a list item works, indented to the item's content column:

1. First step.

   > A note about the first step.

2. Second step.

Attribution and Citations

Markdown has no citation syntax. The conventions in practice:

> The best way to predict the future is to invent it.
>
> Alan Kay

> The best way to predict the future is to invent it.
>
> *Alan Kay, 1971*

> The best way to predict the future is to invent it.

Alan Kay, 1971

A <cite> or <footer> element inside the quote is the semantically correct answer, but it needs raw HTML, which some pipelines strip. In a repository README, italic attribution on its own quoted line is the portable convention.

Thematic Breaks

Three or more of -, *, or _ on their own line renders a horizontal rule. Spaces between the characters are allowed.

---

***

___

- - -

* * *

_______________

All of these produce the same <hr>. Notes:

• Three is the minimum. Two of anything is not a rule.
• The line may contain nothing else, and may be indented up to three spaces.
• A blank line before is not required by the spec, but see the trap below.

The Setext Trap

--- directly under a paragraph is a Setext h2 underline, not a thematic break. This is the single most common Markdown surprise.

Some paragraph text
---

That renders "Some paragraph text" as a level-2 heading. Add a blank line and it becomes a paragraph followed by a rule.

Some paragraph text

---

Two ways to avoid the ambiguity entirely:

• Always leave a blank line before and after a thematic break.
• Use *** for rules, since asterisks have no Setext meaning.

A related collision: --- at the very top of a file is usually the opening delimiter of YAML front matter, so a rule on line 1 will be eaten by any front-matter-aware tool. Start the document with content, not a rule.

GFM Alerts

GitHub renders a blockquote whose first line is one of five markers as a colored callout with an icon. This is a GitHub extension, not CommonMark and not part of the GFM spec.

> [!NOTE]
> Useful information the reader should notice even when skimming.

> [!TIP]
> Optional advice for doing something better.

> [!IMPORTANT]
> Key information the reader needs to succeed.

> [!WARNING]
> Urgent information about a risk that needs attention.

> [!CAUTION]
> Advice about a negative outcome or a dangerous action.

Rules:

• The marker must be the first line of the blockquote, alone on that line.
• The marker is case insensitive in practice, but write it uppercase.
• Exactly these five types exist. Anything else renders as a literal blockquote with bracketed text.
• Alerts cannot be nested inside one another.
• Multi-line and multi-block content is allowed after the marker, as long as each line keeps the > prefix.

> [!WARNING]
> This deletes data.
>
> ```bash
> rm -rf ./cache
> ```

Everywhere other than GitHub (and the few tools that copied the syntax, such as Azure DevOps and some VS Code previews), the marker shows up as literal [!WARNING] text inside an ordinary quote. That is a cosmetic degradation rather than broken output, which is what makes alerts safe enough to use in a README.