Markdown Blockquotes

Blockquotes are used when a piece of content should stand out from the surrounding text. They're commonly used for quotations, notes, warnings, tips, recommendations, and documentation highlights.

Unlike regular paragraphs, blockquotes create a clear visual separation that makes important information easier to find while scanning a page.

You'll see blockquotes in GitHub README files, technical documentation, API references, tutorials, knowledge bases, and project wikis.

Create a blockquote by placing a greater-than symbol (>) followed by a space at the beginning of the line.

Example

> This is a Markdown blockquote.

Output

The > character tells the Markdown renderer to display the line as quoted content instead of a normal paragraph.

💡 Pro Tip: Although some Markdown parsers accept >Text without a space, always write > Text. It improves readability and works consistently across Markdown editors.

Displaying the > Character#

Normally, > starts a blockquote. If you want to display a literal greater-than symbol instead, escape it with a backslash.

Example

\> This is not a blockquote.

Output

For more escaping patterns, see Markdown Escaping Characters.

Once you know the basic syntax, you can combine blockquotes with other Markdown elements to build more useful documentation.

Multi-line Blockquotes#

Prefix each line with > to keep the entire paragraph inside the same blockquote.

Example

> Markdown is a lightweight markup language.
>
> It is widely used for documentation,
> README files, technical blogs,
> and note-taking applications.

Output

Blank lines inside a blockquote must also begin with > to keep the quote intact.

Multiple Paragraphs#

Separate paragraphs with a blank quoted line.

Example

> This is the first paragraph.
>
> This is the second paragraph.
>
> Both paragraphs belong to the same blockquote.

This format works well for documentation notes, explanations, and quoted passages that span multiple paragraphs.

When to Use Blockquotes#

Blockquotes work best when you want readers to pause and pay attention.

Common use cases include:

• Important notes
• Tips and recommendations
• Warnings and cautions
• Quoted text
• Documentation highlights
• Best practices
• References to external documentation

Avoid wrapping large sections of normal content in blockquotes. When everything is highlighted, nothing stands out anymore.

Nested Blockquotes#

Use additional > characters to create nested blockquotes. This is helpful when showing replies, quoted conversations, or multiple levels of commentary.

Example

> This is the main quote.
>
>> This is a nested quote.

You can continue nesting by adding another >.

> Level 1
>> Level 2
>>> Level 3

Although deeper nesting is supported, two or three levels are usually easier to read.

💡 Pro Tip: If you find yourself nesting four or five levels deep, consider splitting the content into separate sections instead. It will be easier to scan on both desktop and mobile.

Blockquotes with Headings#

Headings work inside blockquotes just like they do in normal Markdown.

Example

> ## Important
>
> Always preview your Markdown before publishing.

This pattern works well for highlighted notes, deployment instructions, or documentation callouts.

Blockquotes with Lists#

Lists are commonly used inside blockquotes for steps, recommendations, or feature summaries.

Unordered list

> Features:
>
> - Easy to learn
> - Lightweight
> - Portable

Ordered list

> Setup Steps:
>
> 1. Install Node.js
> 2. Install dependencies
> 3. Start the server

For detailed list formatting, see the Markdown Lists guide.

Blockquotes with Code Blocks#

Fenced code blocks can be placed inside blockquotes when commands or code belong to an important note.

Example

> Example command:
>
> ```bash
> npm install
> npm run dev
> ```

This is commonly used for installation guides, API documentation, deployment notes, and troubleshooting sections.

💡 Workflow Tip: If you're writing longer command examples, format them first in the Markdown Editor, then place them inside the blockquote.

Blockquotes with Links#

Links work exactly the same inside blockquotes as they do in normal Markdown.

Example

> Read the official
> [Markdown Guide](https://www.markdownguide.org/)
> for more information.

This approach is useful when referencing external documentation, specifications, or related resources.

Blockquotes with Images#

Images can also appear inside blockquotes.

Example

> ![Markdown Logo](logo.png)
>
> Official Markdown logo.

Most modern Markdown renderers display images inside blockquotes correctly, although the final appearance depends on the platform. For image syntax, see the Markdown Images guide.

Combining Multiple Markdown Elements#

A single blockquote can contain headings, lists, links, and code blocks together.

Example

> ## Deployment Checklist
>
> Complete the following steps:
>
> - Install dependencies
> - Configure environment variables
>
> ```bash
> npm install
> npm run build
> ```
>
> Review the deployment guide before publishing.

This structure is common in technical documentation because it groups related instructions into one clearly highlighted section without breaking the reading flow.

💡 Pro Tip: Keep each blockquote focused on a single idea. If a note grows into several paragraphs with multiple examples, it's usually better as its own section instead of one large blockquote.

GitHub Flavored Markdown (GFM) extends standard blockquotes with callouts. These are styled blocks that help readers quickly identify notes, tips, warnings, and other important information.

GitHub callouts work in README files, Wikis, Issues, Pull Requests, Discussions, and other places that support GitHub Flavored Markdown. On platforms that don't support them, they usually fall back to a normal blockquote.

Available GitHub Callouts#

NOTE#

Use a NOTE to provide additional context or information that supports the main content.

Example

> [!NOTE]
> Markdown is supported by GitHub, GitLab, VS Code, Obsidian, and many other editors.

Best used for:

• Additional context
• Helpful reminders
• Reference information

TIP#

Use a TIP to recommend a better workflow or save readers time.

Example

> [!TIP]
> Always specify a language identifier after the opening triple backticks for syntax highlighting.

Good examples include productivity tips, documentation shortcuts, and recommended practices.

IMPORTANT#

Use IMPORTANT for information that readers shouldn't overlook before continuing.

Example

> [!IMPORTANT]
> Verify every code example before publishing your documentation.

Reserve this callout for information that directly affects the accuracy or reliability of the documentation.

WARNING#

Use WARNING for actions that could lead to errors, data loss, or unexpected results.

Example

> [!WARNING]
> Deleting production data cannot be undone.

Warnings work best for destructive actions, deployment changes, and configuration risks.

CAUTION#

Use CAUTION when readers need to be especially careful before proceeding.

Example

> [!CAUTION]
> Never commit API keys, passwords, or secret tokens to a public repository.

Security guidance, sensitive operations, and irreversible actions are good candidates for a CAUTION callout.

💡 Pro Tip: Don't use callouts for ordinary paragraphs. When every section becomes a NOTE or WARNING, readers stop paying attention to them.

For a deeper look at GFM features, see GitHub Flavored Markdown.

Support for standard blockquotes is nearly universal, but GitHub callouts are a GitHub Flavored Markdown (GFM) extension and aren't available everywhere.

💡 Workflow Tip: If your documentation will be published outside GitHub, preview the rendered output first. GitHub callouts may appear as plain blockquotes or unstyled text on other platforms.

A few simple habits make blockquotes easier to read and more effective.

• Reserve blockquotes for content that deserves emphasis.
• Keep each blockquote focused on one idea.
• Use GitHub callouts instead of plain blockquotes when publishing on GitHub.
• Avoid nesting more than two or three levels.
• Combine blockquotes with lists or code blocks only when they improve clarity.
• Leave a space after every > character for consistent formatting.
• Preview your document before publishing to verify rendering across different Markdown editors.

💡 Pro Tip: If a blockquote grows into several paragraphs with multiple headings and examples, consider turning it into a separate section instead. Readers can scan shorter notes much faster.

Most blockquote issues come down to small formatting errors. These are the ones you'll run into most often.

Missing Space After >#

Although some Markdown parsers accept it, always include a space after the greater-than symbol.

Incorrect

>This is a blockquote.

Recommended

> This is a blockquote.

Using a space improves readability and produces consistent results across Markdown editors.

Forgetting > on Every Line#

Each line that belongs to the blockquote should begin with >.

Incorrect

> This is the first line.
This line is outside the blockquote.

Correct

> This is the first line.
> This line is also inside the blockquote.

If the > is missing, the blockquote ends and the following text becomes a normal paragraph.

Incorrect Nesting#

Nested blockquotes should follow a logical hierarchy.

Incorrect

>> First level
> Second level

Correct

> First level
>> Second level
>>> Third level

Moving between nesting levels in the wrong order can make conversations and documentation difficult to follow.

Overusing Blockquotes#

Blockquotes work best when they highlight information that deserves attention.

Good candidates include:

• Notes
• Tips
• Warnings
• Best practices
• Referenced quotations
• Important reminders

Avoid wrapping large sections of ordinary content in blockquotes. It reduces their visual impact and makes long pages harder to scan.