Markdown & Code Splitting

1. The Lost Context Problem

Imagine this markdown:

# Pricing
The cost is $10.

# Refund Policy
No refunds allowed.

If you split blindly in the middle, a chunk might just say "No refunds allowed." When retrieved, the LLM doesn't know what has no refunds. Is it the product? The shipping? It lost the header.

2. MarkdownHeaderTextSplitter

We want to attach the header to the content. Chunk 1: Header: Pricing | Content: The cost is $10. Chunk 2: Header: Refund Policy | Content: No refunds allowed.

from langchain_text_splitters import MarkdownHeaderTextSplitter

headers_to_split_on = [
  ("#", "H1"),
  ("##", "H2"),
  ("###", "H3"),
]

markdown_splitter = MarkdownHeaderTextSplitter(
  headers_to_split_on=headers_to_split_on
)

docs = markdown_splitter.split_text(markdown_text)
# Result: metadata={'H1': 'Pricing'} content='The cost is $10.'

3. Why This Wins

By moving stricture into metadata, the LLM always knows the "Parent Context" of any snippet. You eliminate "orphan chunks."

4. Summary

Flat text is bad. Structured text is good. Leverage syntax (Markdown, HTML, Code) to keep context attached to data.

Key Intuition: "Headings are not text; they are metadata."