Why Google Uses Markdown for Developer Docs, per Mueller

Google’s John Mueller recently clarified why the company uses markdown pages for developer documentation, explaining that these formats serve a niche purpose rather than a broad SEO strategy. In a Bluesky thread, Mueller responded to a question from Lily Ray about why Google publishes LLMs.txt files and markdown pages, even though they aren’t required for standard search performance. His focus was on markdown versions of developer docs, not the llms.txt file itself.

Mueller wrote, “The short answer is that it’s not done for search. There’s more to websites than just SEO :-).” He framed his reasoning around two distinct website goals: discovery (being found via search engines) and functionality (helping users complete tasks on the page). He acknowledged the term wasn’t perfect, but compared the distinction to calls to action on traditional pages: “You don’t ‘do them’ for SEO (to be found), but if you’re responsible for the website overall, ensuring a high ‘discovery rate’ (SEO) together with a high conversion rate is useful to justify your work.”

For developer documentation sites like developers.google.com, Mueller argued that markdown versions make sense. “AI coding has gotten very popular, and these coding systems can be (I think) efficient and accurate with the code they produce if they can easily read / parse reference material, such as developer documentation.” He added that markdown helps AI systems “understand the context of the documentation they’re looking at, as well as a simplified version of the reference page.” However, he called this a workaround, noting, “OF COURSE they can read HTML just fine, so this is imo more of a temporary crutch, perhaps to save some tokens.”

For non-developer sites, Mueller was blunt. “For non-developer sites, I don’t think this makes much sense, even with more agentic traffic in the future. Making a markdown version of a shoe’s specs is not going to get you more sales (competitors appreciate it tho).” In a follow-up post, he pushed back against the idea that sites should prepare for a future dominated by AI agents. “And (I know, nobody reads this far), if you think this is important to prepare for when agents are everywhere: your site (all sites) have much more important things to do for SEO than to prepare for a potential future situation that may or may not come. Prioritize needs before dreams.”

Mueller’s comments refine his earlier position. In February, he called serving markdown pages to bots “a stupid idea.” Now, he carves out an exception for developer documentation while holding the line for every other site type. The thread also coincided with reports that Google’s guidance on llms.txt varies by product: its generative AI optimization guide advises skipping llms.txt, while Lighthouse 13.3 added an experimental audit that checks for the file as part of agentic browsing readiness.

Mueller’s distinction between discovery and on-page functionality offers a framework for evaluating whether agentic optimization is worth your time. The test is simple: does building for agents right now produce measurable results for your specific site? His parting advice , “prioritize needs before dreams” , captures a broader industry tension. Vendors are promoting llms.txt and markdown optimization as emerging practices, but neither Google’s search documentation nor independent data supports investing in these for non-developer sites.