--- title: "Docs for AI agents: a checklist | Agent Ready Checklist" description: "Docs for AI agents: a checklist for documentation sites. Evidence from the spec's studies. Commands to check the result." canonical: https://agentreadychecklist.com/guides/docs-for-ai-agents site: "Agent Ready Checklist" last_updated: 2026-11-05 date: 2026-11-05 section: "Guides" --- # Docs for AI agents: a checklist | Agent Ready Checklist > Docs for AI agents: a checklist for documentation sites. Evidence from the spec's studies. Commands to check the result. Source: https://agentreadychecklist.com/guides/docs-for-ai-agents Site: Agent Ready Checklist Last reviewed: 2026-11-05 Agent endpoints: https://agentreadychecklist.com/llms.txt (index), https://agentreadychecklist.com/openapi.json (API), https://agentreadychecklist.com/mcp (MCP server), https://agentreadychecklist.com/ask (search) Access: https://agentreadychecklist.com/auth.md (no key). Pricing: https://agentreadychecklist.com/pricing.md (free). # Docs for AI agents: a checklist for documentation sites Agents reach documentation more than any other part of a site, so a docs site is where the rows pay off first. Make each page answer a task, fence and tag its code, ship an llms.txt and a markdown mirror, and check the headers. This guide gives the six rows and what Mintlify, Docusaurus, GitBook and ReadMe do for each. ## Before you start You need to know which platform builds your docs and whether you can add a file at the site root. In the study behind [AR-READ-04](https://agentreadychecklist.com/checklist/ar-read-04/), 855 of 1,033 agent runs reached the docs and fetched 2,870 docs pages between them, a mean of 3.4 per run that reached them. The Vercel guide prints those counts, and the spec presents the study as Ora's lab finding, which makes the percentages a vendor claim. ## The six rows for a docs site | Row | Ora checks | Mintlify | Docusaurus | GitBook | ReadMe | | --- | --- | --- | --- | --- | --- | | AR-READ-04; Docs that answer agent tasks | none matched | recipe: For each of your top five agent tasks, write a page that holds the steps as text, in order, with the exact names of the buttons, fields and settings. | recipe: For each of your top five agent tasks, write a page that holds the steps as text, in order, with the exact names of the buttons, fields and settings. | recipe: For each of your top five agent tasks, write a page that holds the steps as text, in order, with the exact names of the buttons, fields and settings. | recipe: For each of your top five agent tasks, write a page that holds the steps as text, in order, with the exact names of the buttons, fields and settings. | | AR-READ-05; Fenced, language-tagged code | code-fence-validity | recipe: Fence code with a language and optional title: java HelloWorld.java. | recipe: Fence code with a language: js title="example.js". | recipe: Add a code block and set its syntax to the language (Prism languages); add a caption for the file name. | recipe: Use the code block in the editor (or fenced Markdown in Raw Mode) and set the language for each tab. | | AR-READ-07; Ship llms.txt | llms-txt-exists, llms-txt-formatting, llms-txt-links-resolve | recipe: Automatic llms.txt and llms-full.txt from docs.json navigation; set description in docs.json for the blockquote. | workaround: No generator in core. | recipe: Automatic llms.txt at /llms.txt listing every published page with a Markdown version. | recipe: llms.txt is on by default at /llms.txt. | | AR-READ-09; Advertise a markdown mirror | markdown-link-alternate | recipe: Automatic: pages carry (seen live 2026-11-04) and every page is available with a… | workaround: No .md output per page. | recipe: Automatic on each page and a .md URL for every page. | workaround: Pages answer Accept: text/markdown and .md URLs, but a tag is not documented; rely on Link headers and… | | CF-MARKDOWN-NEGOTIATION; Markdown by Accept | markdown-negotiation-vary, markdown-negotiation | recipe: Automatic: curl -H 'Accept: text/markdown' https:/// returns text/markdown. | workaround: Docusaurus serves HTML for Accept: text/markdown. | recipe: Automatic: Accept: text/markdown returns the page as text/markdown (tested 2026-11-04 on gitbook.com/docs). | recipe: Turn on Markdown for Agents in AI > AI Discoverability; Accept: text/markdown then returns Markdown. | | VERCEL-NEGOTIATION-HEADERS; Markdown headers | markdown-negotiation-vary | recipe: Automatic: markdown responses carry content-type: text/markdown; charset=utf-8 and Vary including Accept (and User-Agent). | workaround: With Cloudflare Markdown for Agents in front, markdown responses get Content-Type: text/markdown; charset=utf-8 and Vary includes Accept. | recipe: Automatic: markdown responses carry content-type text/markdown; charset=utf-8 and Vary includes Accept (live 2026-11-04). | recipe: Automatic with Markdown for Agents: live responses on 2026-11-04 carried text/markdown; charset=utf-8 and Vary: Accept. | Each cell is the first step of the recipe on that platform's page. [Mintlify](https://agentreadychecklist.com/platforms/mintlify/), [Docusaurus](https://agentreadychecklist.com/platforms/docusaurus/), [GitBook](https://agentreadychecklist.com/platforms/gitbook/) and [ReadMe](https://agentreadychecklist.com/platforms/readme/) hold the full recipes and their sources. ## Steps 1. **Make each page answer one task.** Make docs pages answer the tasks users bring to agents. The row's own warning: Docs that list endpoints but never show a full request and response. The kit cannot judge this one, so read your top five tasks by hand. 2. **Fence and tag the code.** Ora's code-fence-validity check tests that fences in served markdown are balanced. It does not test language tags, so check those with the kit's code-fences command on [AR-READ-05](https://agentreadychecklist.com/checklist/ar-read-05/). 3. **Ship llms.txt, and one per docs section if the site is large.** Ora's modular-llms-txt check looks for per-section files such as /docs/llms.txt, as a bonus. [How to ship llms.txt and link it](https://agentreadychecklist.com/guides/ship-llms-txt-and-link-it/). 4. **Serve a markdown mirror and advertise it.** A link with rel="alternate" and type="text/markdown" in the head or a Link header is [AR-READ-09](https://agentreadychecklist.com/checklist/ar-read-09/); Ora's markdown-link-alternate check also asks that the advertised target really serves markdown. 5. **If you negotiate markdown, set the headers.** Answer Accept: text/markdown with Content-Type text/markdown and Vary: Accept, as [VERCEL-NEGOTIATION-HEADERS](https://agentreadychecklist.com/checklist/vercel-negotiation-headers/) says, so a cache does not hand markdown to browsers. 6. **Link the docs from the home page.** Ora's public-api-docs check reads whether documentation you own is linked straight from the homepage. ## What the studies say - Ora's lab found (published 2026-10-21): docs were reached in 83% of runs and fetched more than any other page type, about 3.4 docs pages per run.vendor claim: [github.com/agentready-org/standard/blob/main/spec/spec.md](https://github.com/agentready-org/standard/blob/main/spec/spec.md), read 2026-11-04 - 855 of 1,033 runs reached docs; they fetched 2,870 docs pages in total, a mean of 3.4 per docs-reaching run.primary source: [vercel.com/kb/guide/make-your-site-readable-by-ai-agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents), read 2026-11-04 - Ora's lab found (published 2026-10-21): agents requested markdown on about 65% of web fetches and chose markdown 96% of the time when they named a format; format did not decide task success.vendor claim: [github.com/agentready-org/standard/blob/main/spec/spec.md](https://github.com/agentready-org/standard/blob/main/spec/spec.md), read 2026-11-04 - 2,259 of 3,470 web fetches (65.1%) requested markdown; 2,259 of 2,361 fetches that named a format (95.7%) chose it.primary source: [vercel.com/kb/guide/make-your-site-readable-by-ai-agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents), read 2026-11-04 ## Docs tools profiled here The vendors section profiles 11 docs tools from their own documentation, each with the rows it meets by default: [Docusaurus](https://agentreadychecklist.com/vendors/docusaurus/), [Fern](https://agentreadychecklist.com/vendors/fern/), [GitBook](https://agentreadychecklist.com/vendors/gitbook/), [Material for MkDocs](https://agentreadychecklist.com/vendors/mkdocs-material/), [Mintlify](https://agentreadychecklist.com/vendors/mintlify/), [Read the Docs](https://agentreadychecklist.com/vendors/read-the-docs/), [ReadMe](https://agentreadychecklist.com/vendors/readme/), [Redocly](https://agentreadychecklist.com/vendors/redocly/), [Scalar](https://agentreadychecklist.com/vendors/scalar/), [Starlight](https://agentreadychecklist.com/vendors/starlight/), [VitePress](https://agentreadychecklist.com/vendors/vitepress/). [The docs tools table](https://agentreadychecklist.com/vendors/by-type/docs-tool/) compares them without ranking. ## Sources - [github.com/agentready-org/standard/blob/main/spec/spec.md](https://github.com/agentready-org/standard/blob/main/spec/spec.md)read 2026-11-04 - [vercel.com/kb/guide/make-your-site-readable-by-ai-agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents)read 2026-11-04 - [mintlify.com/docs/create/code](https://mintlify.com/docs/create/code)read 2026-11-04 - [mintlify.com/docs/ai/llmstxt](https://mintlify.com/docs/ai/llmstxt)read 2026-11-04 - [mintlify.com/docs/ai/markdown-export](https://mintlify.com/docs/ai/markdown-export)read 2026-11-04 - [docusaurus.io/docs/markdown-features/code-blocks](https://docusaurus.io/docs/markdown-features/code-blocks)read 2026-11-04 - [docusaurus.io/docs/static-assets](https://docusaurus.io/docs/static-assets)read 2026-11-04 - [docusaurus.io/docs/api/docusaurus-config](https://docusaurus.io/docs/api/docusaurus-config)read 2026-11-04 - [developers.cloudflare.com/fundamentals/reference/markdown-for-agents/](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/)read 2026-11-04 - [gitbook.com/docs/create-content/blocks/code-block](https://gitbook.com/docs/create-content/blocks/code-block)read 2026-11-04 - [gitbook.com/docs/getting-started/llm-ready-docs](https://gitbook.com/docs/getting-started/llm-ready-docs)read 2026-11-04 - [docs.readme.com/main/docs/editor-blocks](https://docs.readme.com/main/docs/editor-blocks)read 2026-11-04 - [docs.readme.com/main/docs/llmstxt](https://docs.readme.com/main/docs/llmstxt)read 2026-11-04 - [docs.readme.com/main/docs/ai-discoverability](https://docs.readme.com/main/docs/ai-discoverability)read 2026-11-04 - [docs.readme.com/main/docs/ai-ready-docs](https://docs.readme.com/main/docs/ai-ready-docs)read 2026-11-04 - [ora.ai/api/checks, contract 1.38.0](https://ora.ai/api/checks?utm_source=agentreadychecklist.com&utm_medium=referral&utm_campaign=guide)read 2026-11-05 Edition Data 2026-11-04 Reviewed 2026-11-05 Spec AgentReady v2.0, 273d2d7 Crawl 13,071 rows, 2026-11-04 Ora 132 checks, contract 1.38.0, 2026-11-05 Verify with Ora The scanner this site recommends for the whole checklist. 132 checks, a score out of 100, no account. `npx ax@0.10 audit --min-score ` [Why Ora, and its limits](https://agentreadychecklist.com/verify-with-ora/) Method - [How rows, commands and rates are made](https://agentreadychecklist.com/method/) - [How an Ora check is matched to a row](https://agentreadychecklist.com/checklist/ora-checks/) - [Pass rates by rank band](https://agentreadychecklist.com/data/by-rank/) Sources and read dates sit at the foot of the page. Last reviewed 2026-11-05. AgentReady v2.0, read 2026-11-04.