Markdown for RAG

Markdown is generally the easiest source format for RAG ingestion — its structure (headings, lists, code blocks) is explicit and lightweight, making structure-aware chunking straightforward compared to PDF or HTML.

Why Markdown Is Comparatively Easy

# Refund Policy

## Standard Items
May be returned within 30 days of purchase.

## Sale Items
Final sale — cannot be returned.

```python
def is_returnable(item):
    return not item.is_sale_item
```

Headings (#, ##), code blocks, and lists are all explicitly marked with plain-text syntax — no need for a heuristic content-extraction algorithm like HTML requires, and no layout ambiguity like PDF requires.

Structure-Aware Chunking Comes Almost for Free

def chunk_markdown_by_headings(markdown_text):
    sections = split_on_heading_markers(markdown_text)
    chunks = []
    for section in sections:
        chunks.append({
            "heading": section.heading,
            "text": section.content,
            "level": section.heading_level  # H1, H2, H3...
        })
    return chunks

Splitting Markdown at heading boundaries naturally produces well-formed, structurally meaningful chunks — directly implementing the structure-aware chunking approach discussed in Chunking Strategies, without needing complex parsing logic.

Preserving Code Blocks Intact

Code blocks should generally be kept intact within a single chunk (not split mid-block) — a code example split across two chunks becomes meaningless in either, and this is an easy, worthwhile special case to handle explicitly in a Markdown chunking function.

Practical Use Case

Technical documentation, README files, and internal engineering wikis are commonly authored in Markdown — a genuinely favorable source format for RAG, and often the reason teams choose to convert other formats (like exporting from a wiki tool) to Markdown before ingestion when possible.

Common Mistakes

• Chunking Markdown with the same generic fixed-size approach used for unstructured text, ignoring the readily available heading structure
• Splitting a code block across chunk boundaries, producing incomplete, unusable code snippets in retrieval
• Stripping Markdown formatting entirely before chunking, losing the structural signal that made Markdown easy to work with in the first place

Interview Relevance

"Why is Markdown often considered an easier source format for RAG than PDF or HTML?" — its explicit, lightweight structural markup (headings, code blocks) enables straightforward structure-aware chunking without complex layout or content-extraction heuristics.

Practice Question

Design a chunking function for a Markdown file that keeps each H2 section as its own chunk, but never splits a code block, even if it makes that chunk larger than the target size.

Related Notes

• Chunking Strategies
• Document Parsing