Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
If your RAG system misses answers that are plainly present in technical documentation, inspect the chunks it retrieves. A Markdown chunker that treats a page as a flat stream can cut a fenced code example in two, separating setup from the logic that uses it—or code from the heading and explanation that make it understandable. Use Markdown-aware boundaries, preserve heading context, and define what happens when a code block exceeds the model’s input budget.
Why splitting a code fence hurts retrieval
A fenced example is usually one unit of meaning: it may include a language label, setup, code, and surrounding explanation. If a size limit lands in the middle of that unit, one chunk can contain the setup without the logic, while another contains code without its prerequisites or the documentation heading that explains its purpose. Retrieval then has less useful context to match against a question or give to a language model. The RAG Handbook describes this problem for code examples and other structured content such as tables and lists: Structure-aware chunking.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Markdown Guide | $7.95 | Buy on Amazon |
| 2 |
|
Using Markdown: A Short Instruction Guide | $9.99 | Buy on Amazon |
| 3 |
|
Markdown: A Complete Guide | $9.99 | Buy on Amazon |
| 4 |
|
Accessible Markdown: Structured Authoring and Reliable Exports | $19.99 | Buy on Amazon |
| 5 |
|
R Markdown Cookbook (Chapman & Hall/CRC The R Series) | $25.31 | Buy on Amazon |
This is not evidence that every missed answer comes from chunking. It is a concrete failure mode to check when the source contains the answer but retrieved passages omit essential code or its explanation.
What a code-aware chunking policy should preserve
- Markdown structure: Prefer boundaries before or after a fenced block, and recognize headings and other meaningful elements instead of splitting only by a fixed character count.
- Explanatory context: Carry the relevant parent heading into a subsection’s retrieved text or metadata so the example retains its topic when retrieved on its own.
- Input-budget compliance: Keeping a fence intact does not mean sending an arbitrarily large block to an embedding model. The chunking policy must account for that model’s input limit.
The RAG Handbook recommends structure-aware boundaries, intact fenced blocks where practical, and parent-heading context. These are design practices, not a universal guarantee of better retrieval: assess their effect on your own corpus and questions.
#1 Best Overall
Choose a strategy with its units and edge cases in mind
Chunking implementations differ in what they count and what structure they recognize. Rag.NET’s documentation distinguishes character-based fixed and recursive approaches from token-aware and structure-oriented strategies. Its recursive approach uses separators, and its documented defaults—when nothing is configured—are 512 characters per chunk with 50 characters of overlap. Those are Rag.NET project defaults, not general recommendations or token counts. See Rag.NET’s chunking documentation.
| Decision | What to check |
|---|---|
| Structure fidelity | Does the method recognize fenced code, headings, lists, and tables, or can a size boundary cut through them? Section-oriented and structure-aware approaches explicitly target meaningful Markdown boundaries. The RAG Handbook discusses these practices; Extend documents a Markdown section strategy for its service. |
| Size measurement | Does the implementation measure characters or tokens? Character counts do not guarantee compliance with an embedding model’s token limit. Rag.NET documents implementation-specific differences between these strategies. |
| Context carried into retrieval | Does the retrieved code chunk include a useful heading and the prose needed to interpret the example, either in the chunk text or attached metadata? |
| Oversized code blocks | Does the chunker emit a block larger than the target, split it silently, or apply an explicit secondary policy? A target chunk size and a model’s input limit are separate constraints. |
| Operational complexity | Parsing Markdown structure adds logic compared with flat-text splitting. A service-specific parser is one option, but integration, cost, and current service terms need separate evaluation. |
Extend documents a Markdown section strategy that preserves Markdown elements across chunk boundaries and carries page and block metadata for citations. That is a description of Extend’s service, not a guarantee about parsers generally; see Parsing for RAG, labeled version 2026-02-09.
Set an explicit policy for code blocks that are too large
An intact code fence may exceed the target chunk size or the embedding model’s input budget. Do not let the chunker’s accidental behavior decide what to do. Choose a policy that fits the example’s structure and the model’s constraints:
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match- Preserve the complete block when it fits the model budget. Keep its explanatory context or heading with it where practical.
- Split only at meaningful internal boundaries when it does not fit. Possible boundaries include logical or syntactic units, but the right split depends on the code; arbitrary character cuts can recreate the original problem.
- Use a separate representation for oversized examples if needed. This is an engineering option, not a universally preferred approach. Ensure retrieval can still associate the representation with the relevant heading and explanation.
The RAG Handbook supports preserving code blocks even when they exceed a target size, while Rag.NET’s documentation illustrates why token limits and character-based sizing should be treated separately. Neither establishes one best oversized-block policy for every pipeline.
Rank #3
Inspect stored chunks, then test retrieval against real questions
- Examine the ingested chunk text. Check whether the opening and closing fences, language label, code, nearby explanation, and heading ancestry remain together or are represented in a way retrieval can use. Reviewing only the original Markdown will not reveal what the index actually stores.
- Change the parser or split rules. Use Markdown-aware parsing or chunking that recognizes fenced blocks and headings. Prefer a boundary before or after a code block, and carry parent-heading context in the text or metadata when a child section may be retrieved alone.
- Exercise the oversized-block policy. Confirm that examples above the target size are handled deliberately and that the resulting input respects the embedding model’s limit.
- Evaluate with representative documentation questions. Include questions requiring specific code details, a parent heading, or the relationship between prose and an example. Compare retrieved passages and answer quality before and after the change.
Inspect the actual returned context, not just whether ingestion completed. The reviewed guidance does not establish a universal quality gain or optimal chunk size, so do not report an improvement percentage unless you measure it on your own evaluation set.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
