In early July 2026, SEOs noticed Google AI Overviews pulling the raw contents of markdown (.md) files directly into their citations: tables and text lifted from a page's underlying markdown rather than its rendered HTML. Google's John Mueller called the behaviour "unexpected" and said it does not mean Google treats markdown files any differently from other content. The short version: this is a crawlability curiosity, not a new ranking lever.
This is part of the crawlers and technical series and a close companion to our pieces on why Google says llms.txt is flawed and the honest take on whether llms.txt is worth it, because the underlying lesson is the same one, from a new angle.
What did people actually see?
Markdown content appearing where you'd expect rendered page content. The observation was surfaced publicly by SEO practitioner Lily Ray, who posted (on Bluesky) an example of markdown-formatted tables showing up inside AI Overview citations and asked whether there was anything SEOs should read into it. John Mueller of Google replied directly:
"That looks unexpected. Can you DM me the details?"
That reply is worth reading precisely. "Unexpected" is not "intentional," and it is not "a signal." It's Google's own engineer saying the surfaced markdown wasn't the product of a deliberate markdown-handling feature. Treat the whole episode as an anecdote from the field. A handful of observed examples in early July 2026, not a documented change to how AI Overviews are built.
Why would a markdown file end up in an AI Overview?
Because Google indexes files on the open web, and a reachable .md file is just another file. There's no exotic explanation needed. If a markdown file is publicly accessible and not blocked from crawling, Google can fetch it, index it, and make it eligible to be surfaced. Including as a source in an AI Overview. The same way any HTML page is. Mueller's framing was exactly this: Google does not consume markdown files (or llms.txt) as special inputs for Search, so what happened is most likely that the crawler simply picked up a markdown file like any other document.
Two things make markdown a slightly more likely candidate to be lifted verbatim than you might expect:
- Markdown is already clean, extractable text. No navigation, no scripts, no chrome. Just headings, lists and tables. That's the exact shape retrieval and answer-generation systems find easy to parse, which is the whole reason we push for semantic, parseable structure in the first place.
- Raw
.mdfiles are often published without anyone deciding they should be. README files, documentation sources, exported content and build artifacts routinely sit at public URLs. Nobody wrote them as pages, but they're crawlable, so they're fair game.
Does this mean markdown is a ranking or visibility lever?
No, and reading it that way is the trap. This is where the episode connects to the larger debate. Google's Mueller has repeatedly pushed back on the idea of publishing markdown-only pages "for the bots," and the reasoning is identical to the llms.txt argument: a stripped, owner-controlled copy you create specifically to influence machines is a weak signal, not a strong one. A markdown file surfacing once by accident doesn't reverse that.
| Reading of the episode | Accurate? | Why |
|---|---|---|
| "Markdown gets a boost in AI Overviews" | No | Mueller: no special treatment; it's indexed like any page |
| "I should publish markdown mirrors of my pages" | No | Same weak-signal mistake as a separate AI-only site version |
| "Anything crawlable can be surfaced, including raw files" | Yes | A reachable .md file is eligible like any other document |
| "My canonical HTML is what I should invest in" | Yes | One set of clean, crawlable pages remains the durable play |
The pattern that keeps repeating: you don't get to choose which version of your content a machine lifts. You only get to control whether the right version. Your real, canonical, crawlable HTML page. Is reachable and clean enough to be the obvious choice.
What should you actually do about it?
Audit what's crawlable, then invest in the canonical page. Nothing here calls for a new markdown strategy; it calls for hygiene and focus.
- Inventory your stray files. Check whether raw
.mdfiles (READMEs,/docssources, exported drafts, static build artifacts) are publicly reachable on your domain. Decide deliberately whether each should be indexable. If a markdown source duplicates a real page, you generally want the HTML page to be the canonical, indexable one. - Don't block AI crawlers by accident, or leave the wrong things open. This is the same discipline as making sure your CDN isn't blocking AI crawlers: know what's reachable and to whom, in both directions.
- Keep your canonical HTML clean and answer-first. The reason markdown looked "liftable" is that it's structured plain text. Your rendered pages should be, too. Real headings, lists and tables, server-rendered, with the facts in the text. Build that into the page you actually want cited, per making your site agent-readable.
- Don't chase the anecdote. One observed behaviour, called "unexpected" by Google itself, is not a roadmap. If you want to influence AI Overviews, the documented levers are still content quality, structure and corroboration. See how to optimise for AI Overviews.
The durable takeaway is the one this series keeps landing on: AI systems reward content that is reachable, clean and corroborated, and they discount signals you fully control. A markdown file drifting into an AI Overview is a reminder that everything on the open web is fair game, so put your effort into the one canonical version you want machines to find, and know exactly what else you're leaving reachable. Tracking which of your pages AI engines actually pull from is what Buffy Intel measures. Questions: [email protected].