---
title: Why txtfirst
desc: The case for markdown as the source of truth, the three arguments that hold, and the two common ones that do not.
order: 4
---

# Why

## The short version

A document written for a parser and rendered for a person is cheaper to serve, cheaper
to read, has nothing to fall out of sync with, and is no worse for people. A document written for
a browser and scraped by a parser is none of those things.

## Three arguments that hold

### 1. The reader you are optimising for changed

Page weight has been justified for twenty years by what it buys the human: layout,
interactivity, brand. That trade is real and it is fine. What is new is that a large
and growing share of your readers discard all of it. They fetch, strip and parse. For
those readers the entire investment is overhead, and there is currently no way for
them to ask you for the cheap version. txtfirst is that way.

### 2. Two representations, one source, and drift you can see

Every organisation that has tried to serve machines has done it by maintaining a
second artifact: an API, a feed, an `llms.txt`, a knowledge base. Second artifacts
drift, because the site breaking is loud and the feed going stale is silent. Deriving
both outputs from one file makes the failure loud instead of silent, which is a
smaller claim than removing it and the only one worth making.

This site broke that rule on its first day. The build produced the combined
`llms-full.txt` by re-reading the source directory instead of reusing the bytes it had
already served, and that second read path skipped a substitution the first one applied.
The file for machines was the one file that went out wrong. A second read path is a
second copy. The build now asserts that no artifact leaves it with an unresolved
placeholder.

### 3. The cost is asymmetric and lands on the reader

Serving 641 KB to deliver 7.7 KB of text costs you a rounding error in bandwidth. It
costs the agent reading you a real amount of context and money, and context is the
scarcest thing an agent has. Whoever is cheapest to read gets read more often and
gets read further. That is not a moral argument, it is a budget.

## Two arguments that do not hold

### "Plain text ranks better"

It does not. Google indexes HTML, and a page served as bare text with no semantic
markup, no headings and no internal links will rank worse than the same content in
ordinary HTML. If you strip the HTML you lose classic search, and classic search is
still where most AI citations are sourced from.

This is why R1 says markdown is the source and not that HTML is forbidden. A txtfirst
site has full semantic HTML, proper metadata and schema.org. It just generates them
from the file instead of hand editing them.

### "Agents prefer markdown, so this wins immediately"

Most crawling today still requests HTML and never sets an `Accept` header. Adopting
txtfirst does not redirect existing traffic to a cheaper path on day one. What it
does is make the cheap path exist, and cost you almost nothing to maintain until
clients start asking for it. Treat it as an option you are buying, not a switch you
are flipping.

## The honest summary

The gain today is a smaller surface, a single source, and a site that is trivially
legible to anything that parses. The gain later depends on clients that mostly do not
exist yet. Adopt it because it is a better way to build a content site, and let the
agent readability be the part that ages well.

## Where the idea comes from

It is not new. `README` files, RFCs as plain text, Jeremy Howard's `llms.txt`,
Cloudflare serving markdown variants at the edge, and every static site generator ever
written all point at the same thing.

Closest in practice is context.dev, a commercial web scraping API, and it is worth
being precise because a first draft of this paragraph was not. Measured on 6 September
2026: every marketing page negotiates on `Accept: text/markdown`, offers a `.md`
suffix, and a `sitemap.md` documents both. That is R2, in production, on a funded
product. On top of that, the homepage alone also hands markdown to any client whose
user agent does not look like a browser, whatever `Accept` says. So the client can
choose everywhere, and on one page the server also guesses.

Two things it does not do. Nothing tells a program where a page's own source lives: no
`Link` header, and the one `alternate` element on a page points at `/auth.md`, not at
that page's markdown. And there is no way to check that the markdown and the HTML came
from one file. And the markdown surface is uneven: the blog index answers 366
bytes of markdown against 584 KB of HTML, which is a stub next to a page, not a
rendering of it. R1 is the difference. Serving markdown is the easy half.

txtfirst only insists on the direction of the arrow: markdown is not an export of the
page, it is the page.