Markdown: Markdown Blockquote Syntax and Nesting
Blockquotes make your documents more persuasive—whether you're citing an expert opinion or highlighting an important note, blockquotes are the best tool for the job.
1. What You'll Learn
- Basic blockquote syntax and usage
- Multi-paragraph and nested blockquotes
- Embedding lists, code, and headings inside blockquotes
- Blockquote best practices in document layout
- Blockquotes vs callout boxes
2. A Technical Writing Trainer's Real Story
(1) Pain Point: Misusing Quotes
Jordan was conducting a documentation writing workshop for a tech team and discovered almost everyone was doing "quoting" the wrong way—some manually indented text in gray font, some used italic, some even pasted screenshots of other people's text. Quotes blended into the main body, making it impossible for readers to tell which parts were the author's own words and which were external sources.
(2) Solution: Unify Quote Formatting with >
Jordan set a team rule: all quoted external text, important tips, and warnings must use the > blockquote syntax. The team's linting script checks for standard quote formatting. Three months later, citation consistency jumped from 30% to 98%.
3. Blockquote Basics
(1) Basic Syntax
Use > at the start of a line to create a blockquote:
MARKDOWN
> This is a blockquote.
> This is the second line of the quote.
💡 Tip: Adding
> to every line is the safest approach. Some parsers also support a single > at the start of a paragraph:
MARKDOWN
> This is a blockquote paragraph with > only on the first line.
This is the continuation (supported by some parsers).
⚠️ Note: For maximum compatibility, add
> to every line.
(2) Blank Lines in Blockquotes
Blank lines inside blockquotes also need a >:
MARKDOWN
> First paragraph.
>
> Second paragraph (with a blank line and `>` in between).
▶ Example: Standard Blockquote Usage
MARKDOWN
In *The Pragmatic Programmer*, the authors point out:
> The core of software development is not writing code, but managing complexity.
> A good programmer is not the one who writes the most code, but the one who makes code clearest.
⚠️ Note: Don't go beyond 3 levels of nesting—readability drops sharply beyond that.
▶ Example: Conversational Nested Blockquotes
MARKDOWN
> **Project Manager:** Can this feature go live this Friday?
>
> > **Developer:** The core functionality is ready, but some edge cases still need testing.
> >
> > > **QA Engineer:** I've run 80% of the test cases. Should have results by Wednesday.
💡 Tip: Nested blockquotes are great for simulating conversations, multi-level comment threads, or showing a quote-within-a-quote (e.g., in academic papers).
5. Other Elements Inside Blockquotes
(1) Headings in Blockquotes
MARKDOWN
> ## Core Argument of the Quoted Material
>
> This is the main body of the quoted content.
>
> ### Sub-Argument 1
>
> Detailed explanation of the sub-argument.
(2) Lists in Blockquotes
MARKDOWN
> Project Requirements:
>
> - Support 1,000 concurrent users
> - Response time < 200ms
> - 99.9% availability
(3) Code Blocks in Blockquotes
MARKDOWN
> **Core Algorithm:**
>
> ```python
> def fibonacci(n):
> if n <= 1:
> return n
> return fibonacci(n-1) + fibonacci(n-2)
> ```
>
> The above algorithm has O(2^n) time complexity and can be optimized with dynamic programming.
▶ Example: Embedding Multiple Elements in a Blockquote
MARKDOWN
> ## Technical Design Review Results
>
> After team evaluation, we've decided to adopt a **microservice architecture**.
>
> | Approach | Scalability | Maintenance Cost |
> |:-----|:------:|:--------:|
> | Monolith | Low | Low |
> | Microservices | High | High |
>
> > Note: Microservices are suitable for teams of 10+. Small teams should start with a monolith.
💡 Tip: Blockquotes can contain headings, lists, code blocks, tables, and most other Markdown elements. This turns a blockquote from "just gray text" into a self-contained content block.
6. Blockquotes vs Callout Boxes
The > syntax and the > **💡 Tip:** patterns used throughout this tutorial are both blockquotes, but serve different purposes:
| Type | Syntax | Appearance | Purpose |
|---|---|---|---|
| Standard Blockquote | > text |
Gray vertical bar | Quoting external sources, dialogue |
| Tip Callout | > **💡 Tip:** text |
Gray bar + icon | Key tips, important notes |
| Warning Callout | > **⚠️ Note:** text |
Gray bar + icon | Warnings, common pitfalls |
MARKDOWN
> Standard blockquote: quoting an external author's viewpoint.
> **💡 Tip:** This is a tip callout—it emphasizes key information for the reader.
> **⚠️ Note:** This is a warning callout—it alerts readers to risks and helps them avoid pitfalls.
💡 Tip: In technical documentation, use standard blockquotes for citing external sources, and emoji-enhanced callouts for tips and warnings. Keeping them visually distinct helps readers quickly understand the intent.
7. Advanced Blockquote Usage in Layout
(1) Using Blockquotes as "Sidebars"
MARKDOWN
## Key Decision
We chose PostgreSQL as our primary database.
> **Decision Rationale:**
> 1. The team has 3 years of PostgreSQL experience
> 2. The project needs complex queries and transaction support
> 3. Tight budget—PostgreSQL is open-source and free
(2) Quotes Within Quotes (Layer by Layer)
MARKDOWN
The original paper states:
> Experimental results show this method is effective.
>
> > Subsequent research further confirms:
> >
> > > After 10 independent replications, the results are consistent.
💡 Tip: Multi-level quotes are common in academic writing, but in technical docs, stick to 2 levels or fewer. The deeper the nesting, the easier it is for readers to get lost.
8. Complete Example: Organizing a Technical Review with Blockquotes
MARKDOWN
# Architecture Review Report
## Review Conclusion
Following the architecture review meeting on June 15, 2026, the team has made the following decisions:
## Database Selection
> **Final Decision:** Adopt PostgreSQL.
>
> **Rationale:**
> - The project requires complex geospatial queries (PostGIS)
> - The team has extensive PostgreSQL experience
> - Compared to MongoDB, PostgreSQL offers more robust transaction support
>
> | Comparison | PostgreSQL | MongoDB |
> |:-------|:----------:|:-------:|
> | Transactions | ✅ ACID | ✅ Multi-doc |
> | Geospatial | ✅ PostGIS | ✅ Built-in |
> | Team Experience | 3 years | 1 year |
## Deployment Plan
> **CEO's Opinion:**
>
> > I suggest starting with a monolith and splitting it once user numbers grow.
>
> **Engineering Team's Response:**
>
> We agree with this strategy. However, the database connection layer will be an independent module to facilitate future microservice migration.
## Reminders
> **⚠️ Note:** During migration, keep the old system running simultaneously for at least 2 weeks to ensure data integrity.
Expected result: A professional architecture review document where blockquotes clearly separate different participants' opinions and the final decisions.
❓ FAQ
Q What's the difference between a blockquote and an indent?
A Blockquotes have a gray vertical bar marker and are visually self-contained blocks. Indentation just shifts the entire block horizontally. Use blockquotes to signal "this content comes from elsewhere"; use indentation for "this continues the main body."
Q Can I put images in a blockquote?
A Yes.
>  renders as an image inside the blockquote. But large images in blockquotes can feel cramped—use sparingly.Q What if a blockquote is too long and hurts readability?
A Trim the quoted content to the most essential lines. If a long passage needs quoting, consider summarizing it in your own words and linking to the original at the bottom.
Q What's the difference between callouts and blockquotes?
A Callouts are essentially blockquotes with added emoji and bold text for visual emphasis. Both render as the same HTML
<blockquote> element.📖 Summary
- Blockquotes use
>, add it to every line for maximum compatibility - Multi-level nesting uses
>>,>>>—don't exceed 3 levels - Blockquotes can contain headings, lists, code blocks, and tables
- Blockquotes are ideal for citing external sources and highlighting key information
- Callouts are enhanced blockquotes with emoji and bold formatting for visual distinction
- Keep blockquotes concise—long quotes disrupt document flow
📝 Exercises
-
Basic: Write a short book review using blockquotes with at least 2 paragraphs separated by a blank
>line. -
Intermediate: Create a double-nested blockquote simulating a "teacher quotes an expert, then a student quotes the teacher's explanation" scenario. Each level should have at least 2-3 lines.
-
Challenge: Write a "Technical Decision Log" that combines standard blockquotes (citing external sources), warning callouts (⚠️ risk alerts), tables (approach comparisons), and code blocks (sample code)—all within a blockquote to test the rendering.
