AI
Plain-text chunking treats a document as an undifferentiated stream of characters — it has no idea that the paragraph under "## Troubleshooting" means something different from one under "## Installation." Markdown files don't have that excuse: they already carry section structure in their #/##/### headers. LangChain's MarkdownHeaderTextSplitter takes advantage of that: it splits Markdown along header boundaries and attaches the header hierarchy to each resulting chunk as metadata, so retrieval doesn't just return isolated text — it returns text plus "this came from the Troubleshooting section."
The two-stage pattern: split by headers, then by size
1. Define which header levels to split on. You pass a list of (marker, metadata key) pairs, e.g. ("#", "Header 1"), ("##", "Header 2") — the splitter uses these to find section boundaries.
2. Run MarkdownHeaderTextSplitter first. Per LangChain's own documentation, each output chunk's metadata field is populated with the header path it fell under (e.g. {'Header 1': 'Setup', 'Header 2': 'Environment Variables'}), and by default the header text itself is stripped from the chunk content.
3. Run a size-based splitter on the results. A header section can still be too long for your target chunk size, so LangChain's docs show piping the header-split output into RecursiveCharacterTextSplitter.split_documents() — note it's split_documents(), not split_text(), specifically so the header metadata carries through to the final chunks.
# Two-stage Markdown chunking: headers first, then size limits
from langchain_text_splitters import MarkdownHeaderTextSplitter, RecursiveCharacterTextSplitter
# 1. Which header levels count as section boundaries
headers_to_split_on = [
("#", "Header 1"),
("##", "Header 2"),
]
# 2. Split by header -- each chunk gets a header-path metadata dict
md_splitter = MarkdownHeaderTextSplitter(headers_to_split_on)
header_splits = md_splitter.split_text(markdown_document)
# 3. Enforce a size limit within each section, preserving metadata
size_splitter = RecursiveCharacterTextSplitter(chunk_size=250, chunk_overlap=30)
final_chunks = size_splitter.split_documents(header_splits)
for chunk in final_chunks:
# chunk.metadata now looks like {'Header 1': 'Setup', 'Header 2': 'Environment Variables'}
print(chunk.metadata, chunk.page_content[:60])| Splitting approach | Retrieved chunk carries section context? |
|---|---|
| Plain character/token splitting | No — a chunk is just text, with no idea what section it came from |
| MarkdownHeaderTextSplitter + RecursiveCharacterTextSplitter | Yes — header path attached as metadata on every chunk |
The header metadata is useful two ways: you can filter retrieval to a specific section (e.g. only search chunks where Header 2 == "Troubleshooting"), and you can show the user which section an answer came from — similar in spirit to the page/element metadata lesson 1 of this course covers for PDFs, but driven by the document's own header syntax instead of a layout-detection model. This only works, though, if the source Markdown actually uses headers consistently — a document that's just flat paragraphs with no # structure gives the splitter nothing to key off, and falls back to acting like a plain text splitter.
Practical Challenge
Take a Markdown file with at least two levels of headers (like a README), run it through MarkdownHeaderTextSplitter, and print each chunk's metadata to confirm it correctly captured the header path.
Concept Check
Sources & Further Reading
- LangChain Docs — Split Markdown by Headers — official documentation for MarkdownHeaderTextSplitter, including the headers_to_split_on syntax and the split_documents() two-stage pattern cited in this article.