If you feed raw HTML to a language model, you pay for things it does not need. Tags, classes, inline styles, script blocks, tracking pixels, a footer repeated on every page.
Markdown keeps the parts that carry meaning. Headings, lists, tables, links and code survive. The rest goes.
Three reasons it matters
Tokens. The same page is far shorter as Markdown. That is context window you can spend on content instead of markup, and money you do not spend per request. The exact saving depends on the site, so measure on yours.
Chunking. Retrieval works best when you split documents at natural boundaries. Markdown headings are exactly that. You can split a docs page on its H2s and each chunk is a coherent section. In HTML you have to guess where sections start.
Signal. Boilerplate repeated across pages ends up in your embeddings. Every chunk “mentions” the cookie banner and the nav. Retrieval gets noisier, and similar-looking pages compete for the same query.
What good conversion does
Not all HTML-to-Markdown is equal. A naive converter keeps the menu and the footer. A good one finds the main content first, then converts, and keeps:
- heading levels
- ordered and unordered lists
- tables
- links, with their targets
- code blocks
That is what the scrape endpoint does, and the crawl endpoint does it across a whole site.
A simple pipeline
- Crawl the docs site.
- Split each page on headings.
- Embed each chunk with its source URL in the metadata.
- Re-crawl on a schedule.
See LLM ingestion for the full flow. And if you only want one site once, run it through the tool on the home page and buy an export.
Measuring it on your own pages
I would not trust anyone’s claim about token savings, including mine, because it depends on the site. Measuring takes ten minutes. Pick five pages you care about. Fetch the raw HTML of each, then convert each to Markdown. Count tokens for both with the tokenizer your model uses. Most tokenizers have a free online counter or a small library. Write the numbers in a table.
You will probably see a large gap on pages built with heavy templates and a small gap on pages that are mostly text. That pattern tells you where conversion pays off. A documentation site with a heavy shell benefits a lot. A plain blog post benefits less. Once you have your own numbers, you can decide whether the extra step is worth it for your pipeline, and you can stop arguing about it in the abstract.
What breaks when you skip conversion
There are failures that are not about cost at all. A model asked to answer from raw HTML can latch onto the wrong text, such as a cookie notice, a related-links box or a footer address. It can quote navigation labels as if they were content. When you embed raw HTML chunks, the markup itself influences the vectors, so two unrelated pages with the same template look more similar than they should. These problems are subtle. Your demo works, and then a user asks a slightly unusual question and the answer comes from the sidebar.
Clean conversion removes the most common sources of that noise before the model sees it. It does not make retrieval perfect, but it takes away a category of mistakes that are boring and hard to debug.
What Markdown does not fix
Markdown is a better format, not a magic one. A page that says nothing useful is still useless in Markdown. A table that is really a layout grid can come out as a confusing table. Content that only appears after you click a tab or scroll may be missing. Pages in several languages stay in several languages. And a conversion can only keep the structure the page had: if the author used bold text instead of headings, you will have bold text instead of headings.
So keep a human check in the loop for the pages that matter most. Read a few converted pages every time you change sources. It is the cheapest quality control in a retrieval project, and it catches problems that no metric will show.
Where to start
If you are building a retrieval pipeline this week, do the small version first. Convert twenty pages, chunk them on headings, embed them with the source URL, and ask questions you know the answers to. If the answers are good, scale up. If they are not, you have a short list of pages to inspect, which is much easier than debugging a thousand.
One last habit: keep the original HTML for a while. If a conversion looks wrong six weeks from now, you will want to compare it with what the page looked like when you fetched it, and a stored copy turns a guessing game into a quick diff.