Markdown Chunker for RAG

Structure first. Every heading starts a new chunk. Within a section, whole blocks — paragraphs, lists, tables, fenced code — are packed together until the next one would go over the token limit. Only a block that is larger than the limit on its own is split further, at sentence boundaries, and as a last resort between words. Code blocks and tables are never cut in the middle unless they are larger than a chunk.

There is no universal answer, but 256–1,000 tokens is the usual range for retrieval: small enough that a retrieved chunk is about one thing, large enough to carry its context. Check your embedding model’s input limit — OpenAI’s text-embedding-3 models accept up to 8,191 tokens — and test retrieval quality on real questions.

It repeats the last few dozen tokens of one chunk at the start of the next, so a sentence that straddles a boundary can still be found from either side. 10–15% of the chunk size is a common starting point; overlap never crosses a heading, since a new section starts fresh.

A chunk that says “Set the timeout to 30 seconds” is ambiguous on its own; prefixed with “# API guide > ## Retries”, it is not. Repeating the heading path makes every chunk self-describing, which usually improves both retrieval and the answer generated from it.

One JSON object per line: id, text, tokens, headings (the heading path as a list) and the tokenizer used. It loads directly into most vector-database import tools, LangChain and LlamaIndex, or a few lines of Python.

No. Text extraction, tokenization and chunking all run in your browser, in a background thread.