Claude can build your docs site in 13 minutes. Here's what it leaves out.
We gave a fresh Claude Code session one paragraph and no help. In 13 minutes it built a fast, good-looking docs site. Then we counted everything else a docs site does.
One paragraph in. A real docs site out.
A fresh Claude Code session: no memory, no instructions file, no plugins, no help. This is the whole prompt.
Honestly, it's good. Static, fast, and easy for crawlers to read. Its search even forgives typos. If this is all your docs will ever need, use it.
Run on 2 November 2026 with Opus 5.5 in a sandbox, using the Swagger Petstore spec as a stand-in for a real API.
things a docs site does. Claude built 32 of them, and built them well.
We listed everything readers and writers take for granted on a docs site and checked each one. 15 were partly there: they work, but only through Git, a script or a config file. 64 weren't there at all. Nobody asked for them. Nobody ever does.
Hover a square to see what it is. Every one is listed further down.
A brand-new docs site, built with AI. It loads like it's 1999.
How long a page takes to load when nobody has opened it recently, week by week since launch.
This autumn, a software company with thousands of pages of docs launched a new docs site, made with Claude Code. Building it and moving their docs across took at least six months. The site builds each page the moment someone opens it, and keeps recently opened pages ready.
Popular pages load quickly. But most of their thousands of pages aren't opened often enough to stay ready. Six months of work, and most readers wait four seconds for a page. More than a month after launch, nothing has changed.
- The docs
- Thousands of pages
- Made with
- Claude Code
- Time to build and move
- At least six months
- How it works
- Each page is built when someone opens it. Recently opened pages are kept ready.
- What people see
- Popular pages load fast. Everything else takes about four seconds.
- What AI agents see
- Four seconds, on almost every page
- A month later
- Still four seconds
For AI agents, it's worse.
An AI agent answering one question can read ten pages, and it reads the deep ones that nobody has opened today. Those are exactly the pages that take four seconds.
The person who asked has stopped waiting. A docs site that's slow for AI doesn't work in 2026, however new it is.
docs readers are now AI agents and assistants. Every one of them waits the four seconds.
AI Docs Report, October 2026The trap is that a docs site is a second product wearing the costume of a chore.
Here's the second product: 79 things nobody asked for, and everybody needs eventually.
Your support lead shouldn't need Git to fix a typo.
Claude built a site for developers, edited by developers. The day someone else writes, you need an editor, drafts, reviews, roles and history, and all of it has to stay in sync with Git.
“dont make them learn branches, rebases, and PR etiquette unless they actually want to.”
A static site can't keep a secret.
Your first enterprise customer wants their docs behind their own login. That takes a server, a login, audiences, and every copy of a private page kept out of public view. One team on r/Docusaurus spent days on it. Asked if they solved it: “Unfortunately not.”
“They are stateless, which means there's no way they can handle SSO.”
Two in five docs readers are now AI. They read differently.
Crawlers read Claude's static pages fine. Agents want something else: Markdown at the page URL, an llms.txt, an MCP server, and private pages kept out of all of it. The list of agents changes every week.
“After Bun reported a 10x token reduction by serving markdown docs to Claude Code, I implemented the same approach for our docs site.”
We ran these against the site Claude built. An agent that asks for Markdown gets the full web page, scripts and all.
Rendering an API reference is solved. Everything around it isn't.
Claude's reference looks right: a page per endpoint, schemas, samples in four languages. Then a reader clicks Try it, support pastes a link to one field, a spec update renames an endpoint, and a writer wants to fix a description without touching YAML.
Search was the easy part. Then readers started asking questions.
To be fair, Claude's search is good: “authentcation” finds Authentication. What it can't do is answer a question, hide private pages, or tell you what readers looked for and didn't find.
“I tried Algolia with Ask Ai feature, but it feels more like traditional search than an agent that understands questions and provides useful answers.”
The search above is real: Claude's site has no page about pagination. The assistant below it is what readers expect now.
Your second language doubles everything.
Every page, the sidebar, search, the landing page and the API descriptions, retranslated whenever the English changes, and only the sentences that changed. Code and schema keys stay as they are.
“the build for Docusaurus gets slow once you add a second language. Our build takes about 25 mins.”
The sidebar, the page and the search all switch together. The code never does.
v2 ships. v1 customers still need their docs.
Versions mean two copies of everything, search that knows which one you're reading, and a redirect for every page that ever moved, in every version.
“Versioned docs = major maintenance headache.”
Each version gets its own pages, its own search index and its own API reference, and the canonical link points search engines at the latest.
Nobody notices these until they're gone.
Each one is small. Together they're the difference between a docs site and a folder of pages.
“every small change is turning into fixing navigation, search, styling or something else that has nothing to do with the actual project.”
Everything Claude left out needs servers.
Claude's site is a folder of files on a fast network. That's why it's quick, and why it can't treat one reader differently from another. The first login, the first draft or the first private search needs servers. And servers need all of this.
One way to build it, not a map of ours. Your choices will differ. The number of parts won't, by much.
Each part breaks in its own way.
It backs up. A page you published an hour ago still isn't live, and search still shows the one you deleted.
It's emptied by a release. Every reader waits for a cold render at the same moment.
It goes down. Every customer with private docs is locked out, and support hears about it first.
It runs out of memory. Every search comes back with no results.
Your provider has an outage. The assistant goes quiet, unless you built a fallback.
Its disk fills up. The editor stops saving, mid-sentence, for every writer at once.
Every one of the 49 has to be sized, secured, monitored, backed up, patched and paid for. The prompt at the end of this page has all of them.
Now it's worth breaking into.
A folder of public pages has little to steal. A server with customer logins, private docs, API keys typed into try-it and a pipeline that can publish has plenty. And the threats don't wait for your roadmap.
to patch a critical bug once it's being exploited. Saturdays included.
Patching means more than bumping a version. Every container image that bundles the library gets rebuilt, every process restarts, and someone checks that nothing else pulled in an old copy. Then the next advisory arrives.
One AI crawler made about 70,000 requests in a couple of minutes and used up a nonprofit's whole free hosting tier.
A site went from under 3 million requests a month to 40 million, all from one AI company's crawler.
Whatever you build today won't be good enough next month.
The site Claude built is good for the web of November 2026. llms.txt was proposed in September 2024. MCP arrived that November. In our last report, Claude's share of AI assistant traffic to docs went from 7% to 38% in three months.
Whatever comes next, your docs will need it in weeks, not quarters. That's not a project you finish. It's a team you keep.
New AI search engines, coding tools, assistants and research agents start reading docs all the time. Each one has to be recognised, or it gets a page built for a browser instead.
This year, we've shipped changes to DeveloperHub on most days.
We've been at it since 2018, and we've never shipped more than this year. AI made our team faster. The list grew faster.
The API bill is the cheap part. The team is the expensive part.
Claude can write the code. Someone still has to own it: review it, deploy it, fix it on a Saturday, and rebuild it when the web changes. That's not a prompt. It's a salary.
Sometimes you should build it yourself.
Then Starlight or Fumadocs with Pagefind is excellent, and Claude will set it up in an afternoon.
“We just moved to it from Docusaurus and couldn't be happier.”
The day you need one of the 79, you're maintaining a product.
Here's the whole prompt.
All 111 rows on this page, every place one row touches another, the 49 moving parts underneath, the security policy and the runbook, written as a spec your agent can build from. 86,082 words. Feed it to Claude Code. Then keep it current, every week, forever.