When markdown mirrors help, and when they do not

Generated markdown mirrors are useful for some sites and unnecessary for others. The honest answer depends on what your raw HTML already looks like and whether agents need a cleaner fetch target than the page you already serve.

The problem mirrors are trying to solve

A public page can be technically crawlable and still be a bad machine-facing document. If the response is mostly app shell, navigation, layout wrappers, and scripts, fetch-based agents have to infer the real page body from noisy HTML.

A generated markdown mirror gives those agents a simpler fetch path: title, description, source URL, headings, lists, paragraphs, and code blocks without the surrounding chrome.

Where markdown mirrors help

• Thin client-rendered pages. If the raw HTML is mostly shell before JavaScript runs, a mirror can be the only useful body content a fetch-based agent sees.
• Layout-heavy pages. Marketing pages with large nav trees, cookie UI, scripts, and repeated components can benefit from a cleaner derivative.
• Sites that want an explicit machine-facing fetch target. A mirror can sit alongside llms.txt and JSON-LD as another agent-readable artifact.
• Teams that want deterministic output. A build-time derivative is easier to inspect and debug than a runtime readability layer you do not control.

Where markdown mirrors do not add much

• Server-rendered content sites with good HTML. If the raw page already contains substantial readable body content, HTML may already be enough.
• Markdown-authored static sites. If you already author in markdown and publish strong HTML, a second public markdown output is often unnecessary.
• Pages where the extraction loses meaning. Tables, interactive widgets, or complex layouts can become less accurate when flattened to markdown.

This is why the strongest version of the feature is not "every page should publish markdown". It is "some pages benefit from a cleaner machine-facing artifact".

The real tradeoffs

The objections are real. Public mirrors can create duplicate fetches and indexing ambiguity. If they are hand-maintained, they also create a second source of truth that will eventually drift.

There is also a product risk: as agent tooling gets better at reading messy HTML directly, the gap that mirrors solve may narrow. That makes this more likely to be a tactical feature than the final shape of machine-readable publishing.

How agentmarkup tries to keep the feature disciplined

• Generated from final HTML. The mirror is derived from the built page, not maintained separately by hand.
• Canonical headers point back to HTML. The HTML page stays the preferred canonical page for search engines.
• The checker is conditional. Missing markdown is treated as a real issue only when the paired HTML is thin.
• llms.txt can stay HTML-first. If your raw HTML is already substantial, set llmsTxt.preferMarkdownMirrors to false.

The more durable product surface

The long-term durable value is probably not "every site needs markdown mirrors". It is better tooling around agent-readiness: checking raw HTML quality, validating machine-readable outputs, verifying crawler policy, and making tradeoffs explicit.

That is why the checker matters. It can tell you whether the HTML is already good enough, whether a markdown mirror would add signal, and whether the rest of your machine-readable surface is coherent.

The bottom line

Markdown mirrors make sense as an optional, tactical feature for thin or noisy HTML. They are not a universal best practice, and they should not be marketed as one.

If your raw HTML already reads cleanly, keep HTML as the primary fetch target. If it does not, a generated markdown derivative can be a pragmatic bridge while the broader machine-readable stack keeps improving.