# Serving Clean Markdown Solves Retrieval but Not Discovery A docs platform that answers `Accept: text/markdown` with a clean file solves retrieval: an agent that names a page gets that page without nav chrome. It doesn't solve discovery, because the agent still has to know which page to ask for. Andrew Sepic, a senior frontend engineer at Mapbox, says the job seemed done once markdown shipped everywhere, then states the gap: "It doesn't answer which page in your docs answers my question." (00:07:23) The retrieval half is real engineering. Mapbox builds each of its 2,000+ pages twice with Docusaurus, once as HTML and once as a `.md` route. Components simplify their own output to plain HTML, Turndown converts that to markdown, and a post-build step writes `llms.txt` and `llms-full.txt` (00:05:12). At the edge, the server normalizes the Accept header for cache stability, rewrites the URL to the `.md` file in S3, and falls back to HTML. About 99% of pages serve markdown directly (00:06:39). In one week, 460 humans used copy as markdown or view as markdown, against 47,000 LLM requests to markdown paths, about 102 agent requests per human use (00:06:39). The discovery half is where the work moves. Sepic's answer is a docs MCP server, and the open problem is getting users' agents to use it instead of falling back to web search (00:07:23). The tactics are MCP connect options in the copy-as-markdown menu for Claude, Cursor and VS Code, a human-facing guide page, and an MCP link injected at the top of `llms.txt` (00:08:08). Two other talks at the same event show why format isn't the bottleneck. Hahnbee Lee of Mintlify reports that accuracy was "pretty good across the board" for llms.txt, markdown and HTML, though agents seek out llms.txt and markdown files (00:14:37). Caelean Barnes shows a Claude Code trace where the agent finds vendor docs through web search and page fetch (00:03:50), so a search engine is doing the discovery job today. Where this breaks. The 460, the 47,000 and the 99% come from one week at one company. Sepic gives no method for separating humans from bots or LLMs from crawlers, no count of the 1% that fall back to HTML, and no baseline. The MCP distribution updates are "in review right now" (00:08:08), so the claim that they fix discovery has no result behind it. The `llms.txt` link idea is credited to "David from Kappa," which is likely a caption garble of a company name and is untested. Lee's benchmark has no sample size or scores. The split between retrieval and discovery is a mechanism the talk argues, not a measured outcome, and it weakens when an agent already holds a path from a sitemap or search result. <!-- atomicity: 1 idea ✓ --> ## Why This Matters Before calling a docs set agent-ready, I'd run two checks: curl one page with `Accept: text/markdown` and read what returns, then ask an agent a task question with no URL and see whether it lands on the right page or falls back to web search. The first tests retrieval and the second tests discovery. A pass on the first says nothing about the second. ## Links - [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]] — extends: that note covers the cost of the format machines read, and this one covers what format alone leaves unsolved. - [[3. Resources/Permanent Notes/A Shared Schema Turns Distribution Into Retrieval]] — contrasts: a shared structure makes reading a known format easy, and agents still need a way to find which page holds the answer. - [[3. Resources/Permanent Notes/Concentration Beats Coverage Under Retrieval]] — applies-in: once retrieval returns fragments, one canonical page per decision is easier to discover than several near-duplicates. - [[3. Resources/Permanent Notes/A Skills Repository Is the Client Library for an MCP Server]] — evidence-for: both treat the MCP server as the layer that tells an agent how to find and use the tool. - [[3. Resources/MOCs/Documentation & Technical Writing MOC]] — applies-in: docs-platform readiness for agents, retrieval versus discovery. - [[3. Resources/MOCs/Events/DevRelCon NYC 2026 MOC]] — applies-in: the docs-for-agents cluster, alongside Lee, Barnes and Whinnery. ## Source - [[3. Resources/Readwise/Articles/Copy as Markdown Is Table Stakes. Is Your Docs Platform Ready — Andrew Sepic|Copy as Markdown Is Table Stakes. Is Your Docs Platform Ready? — Andrew Sepic]] - https://www.youtube.com/watch?v=pBZ6NUu9T-E - Second voices: [[3. Resources/Readwise/Articles/Developer First = Agent First — Hahnbee Lee|Developer First = Agent First — Hahnbee Lee]], [[3. Resources/Readwise/Articles/Agent Led Growth How to Get Claude Code to Pick Your Dev Tool — Kara Silverman & Caelean Barnes|Agent Led Growth — Silverman & Barnes]]