{"slug":"build-an-agent-readable-docs-site","id":"build-agent-readable-docs-site","type":"guide","title":"Build an Agent-Readable Docs Site","description":"A practical recipe for making documentation readable by AI agents with markdown source, discovery files, schema, search index, feeds, and hashes.","last_updated":"2026-04-24","last_verified":null,"verification_status":"unverified","markdown_url":"/content/guides/build-an-agent-readable-docs-site.md","html_url":"/guides/build-an-agent-readable-docs-site","api_url":"/api/v1/guides/build-an-agent-readable-docs-site.json","content_hash":"a2a6bb4e9ed9d48e1e15e25f3fd59805081ee0c3913e7fb390f708657c7bc04a","sha256":"a2a6bb4e9ed9d48e1e15e25f3fd59805081ee0c3913e7fb390f708657c7bc04a","tags":["recipe","agent-ready","docs","markdown","discovery"],"relationships":{"links":[],"related":[{"id":"agent-usage-guide","title":"Agent Usage Guide","type":"guide","html_url":"/guides/agent-usage","markdown_url":"/content/guides/agent-usage.md","shared_tags":["discovery","markdown"],"score":4},{"id":"build-a-coding-agent-stack","title":"Build a Coding Agent Stack","type":"guide","html_url":"/guides/build-a-coding-agent-stack","markdown_url":"/content/guides/build-a-coding-agent-stack.md","shared_tags":["recipe"],"score":3},{"id":"build-ai-research-assistant","title":"Build an AI Research Assistant","type":"guide","html_url":"/guides/build-an-ai-research-assistant","markdown_url":"/content/guides/build-an-ai-research-assistant.md","shared_tags":["recipe"],"score":3},{"id":"choose-model-for-customer-support","title":"Choose a Model for Customer Support","type":"guide","html_url":"/guides/choose-model-for-customer-support","markdown_url":"/content/guides/choose-model-for-customer-support.md","shared_tags":["recipe"],"score":3},{"id":"local-models-private-documents","title":"Use Local Models for Private Documents","type":"guide","html_url":"/guides/local-models-for-private-documents","markdown_url":"/content/guides/local-models-for-private-documents.md","shared_tags":["recipe"],"score":3},{"id":"agent-tooling-compatibility","title":"Agent Tooling Compatibility","type":"guide","html_url":"/guides/agent-tooling-compatibility","markdown_url":"/content/guides/agent-tooling-compatibility.md","shared_tags":[],"score":2}],"explicit":{}},"metadata":{"title":"Build an Agent-Readable Docs Site","type":"guide","id":"build-agent-readable-docs-site","description":"A practical recipe for making documentation readable by AI agents with markdown source, discovery files, schema, search index, feeds, and hashes.","last_updated":"2026-04-24","tags":["recipe","agent-ready","docs","markdown","discovery"]},"content_text":"# Build an Agent-Readable Docs Site\n\nUse this recipe when a user wants agents to read, cite, monitor, and use their documentation reliably.\n\n## Minimum Viable Agent-Readable Site\n\n- Markdown source for every page\n- YAML or JSON metadata\n- `/llms.txt`\n- `/content/` raw files\n- `/api/v1/index.json`\n- `/search-index.json`\n- `/feed.json`\n- `/sitemap.xml`\n- `robots.txt` that allows content and API paths\n\n## Better Version\n\nAdd:\n\n- `/.well-known/ai.json`\n- `/api/v1/schema.json`\n- per-item JSON\n- content hashes\n- changed-since endpoint\n- source and verification metadata\n\n## Content Rules\n\n- One canonical source per page.\n- Stable IDs that survive URL changes.\n- Dates that mean content change, not deploy time.\n- Typed metadata for fields agents filter on.\n- Raw content that works without JavaScript.\n\n## Agent Test\n\nAn agent should be able to answer:\n\n- What content exists?\n- What changed since my last visit?\n- What is the raw source for this page?\n- What schema should I expect?\n- Can I verify my cached copy?\n\n## Failure Mode\n\nThe common mistake is shipping a JSON API that drifts from the human docs. Use one content source and generate every representation from it.","content_length":1533,"generated_at":"2026-04-24"}