Blockquotes in MDX

Blockquotes are one of those Markdown features that seem simple on the surface — just put a > at the start of a line. But they are incredibly versatile when you understand all the patterns available to you. In documentation and educational content, blockquotes serve as callouts, warnings, tips, attribution blocks, and conversation threads. Let us explore every way you can use them effectively.

Multi-Paragraph Blockquotes

When your quote spans multiple paragraphs, use a blank line with just > on it to create paragraph separation within the blockquote:

  | First paragraph of the quote. This sets up the context
  | for what the author is about to explain in detail.
  |
  | Second paragraph, still part of the same blockquote.
  | The blank line with just > creates the paragraph break
  | while keeping everything inside one blockquote container.
  |
  | Third paragraph with the conclusion of the quoted material.

The key is that the blank line must still have the > character on it. If you leave a completely blank line (without >), the blockquote ends and a new one begins.

Nested Blockquotes

Stack the > symbols to create nested quotes — useful for showing conversations, responses to responses, or hierarchical quoted material:

  | Original statement from the first person.
  |
  |   | Someone's reply to that statement.
  |   |
  |   |   | And a third person's reply to the reply.

This pattern is particularly useful for:

• Showing email threads or message conversations
• Demonstrating discussion forum exchanges
• Illustrating back-and-forth dialogue in case studies

Practical limit: Do not nest more than 3 levels deep. Beyond that, the indentation becomes difficult to read on mobile screens and the source file becomes hard to maintain.

Blockquotes with Rich Formatting

You can use any Markdown formatting inside blockquotes — bold, italic, code, links, lists, and even headings:

This flexibility means blockquotes can contain entire sections of structured content, not just plain text.

Attribution Pattern (Citing Someone)

The classic quote-with-source pattern is one of the most common uses of blockquotes:

There is no official Markdown syntax for attribution. The em-dash before the author name is simply a convention that everyone uses. Some documentation sites style this differently with CSS, making the attribution line smaller or italic.

For academic or professional citations, you might include more detail:

Callout Patterns for Documentation

Many modern documentation sites use blockquotes as callout boxes. The pattern is simple: start with an emoji and a bold label:

This approach works everywhere — no plugins needed, no special syntax, just a blockquote with an emoji and bold label. It is the simplest way to create visually distinct callouts without framework-specific features.

Why this pattern is popular:

1. It works in any Markdown renderer — GitHub, GitLab, MDX, Hugo, Jekyll
2. It requires zero configuration or plugins
3. It is accessible — screen readers read the emoji description and bold text
4. It is visually scannable — readers instantly recognize the pattern
5. It degrades gracefully — even in plain text, the meaning is clear

Blockquotes for Code Context

When explaining code, blockquotes work well for providing context about what the code does or when to use it:

This creates a clear visual separation between the contextual explanation and the code itself.

When to Use Blockquotes

Good uses:

• Quoting someone — the obvious and original purpose
• Callouts and warnings — emoji + bold label pattern for attention-grabbing notices
• Highlighting important information — when you want text to stand out from the flow
• Showing conversations — nested quotes for back-and-forth exchanges
• Providing context — setup information before code examples
• Legal disclaimers — terms, licenses, or attribution notices

When NOT to use blockquotes:

• Do not use blockquotes for code — use code blocks (\\\`) instead
• Do not use them for every other paragraph — it loses impact when overused
• Do not nest more than 3 levels deep — becomes unreadable
• Do not use them purely for visual indentation — use proper structure instead
• Do not put entire sections in blockquotes — they should be brief and focused

Styling Blockquotes with CSS

In most MDX-powered sites, you can style blockquotes through your CSS or theme configuration:

Different callout types can be styled using CSS selectors that target the emoji or label text, or you can build a custom React component for more sophisticated callout boxes.

Quick Reference

Key Takeaways

Blockquotes are deceptively powerful. They start as a simple quoting mechanism but become your primary tool for callouts, warnings, tips, and contextual information in documentation. Master the emoji + bold label pattern and you have an instant, portable callout system that works in any Markdown-based platform without plugins or configuration.