Should you publish Markdown versions of your web pages for AI?

Web publishers have spent years serving two audiences: people reading pages in browsers and search engines crawling them. AI agents add a third. Coding assistants, research tools, browser agents, ChatGPT search, Claude, and Perplexity can all retrieve web content, although they do not necessarily retrieve it in the same way.

That leaves publishers with a practical choice. Should a website keep its normal HTML pages and also provide a clean Markdown version of each useful article or page?

https://example.com/guides/coffee-brewing/
https://example.com/guides/coffee-brewing.md

The content is the same. Only the representation changes.

Google does not use Markdown files as a ranking signal, and OpenAI, Anthropic, and Perplexity do not promise extra search visibility to sites that publish them. Yet Cloudflare, Mintlify, and OpenAI's own developer documentation now deliver Markdown for machine-oriented workflows. The format has a real use, but it is narrower than the early “AI SEO” pitch suggested.

Updated October 18, 2026: This version covers current guidance from Google and AI providers, Cloudflare's Markdown for Agents, OpenAI's Markdown documentation, the latest available citation research, the v2 llms.txt proposal, and Publii's plugin integration.

What a Markdown alternative changes

A typical webpage contains much more than the article. Navigation, cookie notices, forms, related posts, social buttons, layout wrappers, styles, and scripts all surround the information a reader came for.

A browser needs that material to construct an interactive page. A tool looking for the article has to identify the useful content and discard the interface around it. Modern agents can already do this with HTML, so a Markdown copy is not required. It gives a client that prefers structured text a smaller document to retrieve and process.

Instead of receiving:

<article class="post">
    <header class="post__header">
        <h1>How to brew better coffee</h1>
        <div class="post__meta">
            <span>Published August 14, 2026</span>
        </div>
    </header>

    <div class="post__content">
        <p>Good coffee starts with the right ratio...</p>

        <h2>Choose your beans</h2>

        <p>Freshly roasted beans...</p>
    </div>
</article>

the same client could receive:

# How to brew better coffee

- URL: https://example.com/guides/coffee-brewing/
- Published: 2026-08-14T10:00:00.000Z

Good coffee starts with the right ratio...

## Choose your beans

Freshly roasted beans...

Markdown removes presentation markup while preserving headings, lists, links, quotations, tables, and code blocks. It is also a familiar web format rather than an AI-era invention. John Gruber introduced it in 2004, and the IETF registered the text/markdown media type in RFC 7763 in 2016.

Markdown has moved into production

Cloudflare introduced Markdown for Agents in February 2026. An enabled site can serve the existing page as Markdown when a client requests text/markdown:

GET /article/ HTTP/1.1
Host: example.com
Accept: text/markdown

Cloudflare fetches the HTML, converts it at the network edge, and returns a different representation of the same URL:

HTTP/1.1 200 OK
Content-Type: text/markdown

The token savings can be substantial on markup-heavy pages. Cloudflare's launch article contained 16,180 tokens as HTML and 3,150 after conversion, a reduction of roughly 80% for that page. Its Markdown for Agents documentation shows another response with 725 Markdown tokens against 12,345 original tokens. These are examples, not a universal benchmark; a clean article page and a complex application page will produce very different ratios.

More importantly, clients are asking for the format. Cloudflare says Claude Code and OpenCode already send the relevant Accept header, and its Radar example shows Markdown responses delivered to OAI-SearchBot. That confirms retrieval. It does not tell us that Markdown changes how a page is ranked or cited.

Mintlify takes a similar approach for documentation. It supports both a predictable .md URL and HTTP content negotiation:

/docs/getting-started
/docs/getting-started.md

OpenAI now uses the same pattern on its developer site. Its documentation links to a complete llms.txt index and states that a Markdown version of a page is available by appending .md to the URL. That is a useful example of the workflow in practice. OpenAI's crawler documentation still does not describe Markdown as a requirement or ranking signal for ChatGPT Search.

How Markdown relates to llms.txt

An llms.txt file can provide a short index of the resources an agent may need. Our complete guide to llms.txt covers the format and its current support in detail.

# Example website

> Guides and resources about static website development.

## Guides

- [Installing Publii](https://example.com/install.md): Installation instructions
- [Creating a website](https://example.com/create-site.md): Getting started guide

The index helps a compatible tool find a document. The Markdown URL provides the document itself. A site may use one without the other.

Version 2 of the llms.txt proposal, published in August 2026, recommends advertising a Markdown alternative from the HTML page:

<link rel="alternate" type="text/markdown" href="https://example.com/page.md">

It also uses rel="describedby" to point a page toward the relevant llms.txt file. Both relationships can appear as HTML <link> elements or HTTP Link headers. The proposal recognizes /page.html.md and /page.md as possible URL patterns.

This is still a community proposal rather than a universal web standard. Publishing the relationship makes the alternate document discoverable to software that supports it; it cannot make other clients use it.

What the evidence shows in 2026

Google's guidance for generative AI features in Search is explicit. Google Search does not use llms.txt, AI text files, special markup, or Markdown for ranking. Maintaining them for another service will neither help nor harm visibility in Google Search.

OpenAI documents OAI-SearchBot, GPTBot, and ChatGPT-User. Anthropic documents ClaudeBot, Claude-SearchBot, and Claude-User, while Perplexity documents PerplexityBot and Perplexity-User. Their public crawler guidance explains access and crawler roles, but none promises a ranking advantage for parallel .md files.

The available measurements do not show one either:

• In a three-week randomized experiment by Profound across 381 pages on six websites, Markdown pages received roughly one additional median bot visit. The mean lift was about 16%, driven mainly by pages that already had heavy bot traffic, and the result was not statistically significant.
• In a seven-day Promptwatch sample of 1,665,674 citations across ChatGPT, Claude, Perplexity, and Google AI Overviews, Markdown URLs accounted for 0.05%. The measurement tells us which URLs were cited, not every representation a system may have processed before producing an answer.
• In an exploratory test covering five websites and nearly 18,000 citations, Malte Landwehr reported that sites offering Markdown copies were cited more than 3,500 times, but none of those citations pointed to the alternate .md URLs. GitHub was a separate case because Markdown files there are often the normal public document.

If the goal is more search citations, these results do not justify building Markdown copies. The stronger case is operational: an agent that already wants a document may retrieve a smaller, cleaner representation and spend less work separating the content from the page interface.

Keep HTML primary and keep both versions consistent

HTML remains the main publishing format for the web. It carries navigation, interactive elements, forms, media, accessibility information, metadata, structured data, and the other parts of a working website. Modern agents can use rendered pages, the DOM, and accessibility trees, so good HTML already serves machines as well as people.

/article/       → primary HTML page
/article.md     → alternate Markdown representation

The alternate file should contain the same substantive information as the HTML page. It may remove navigation, cookie controls, sharing buttons, layout instructions, and other interface material that makes no sense in a text document. It should not become a second article with different claims, hidden promotional instructions, or content written only for AI systems.

HTML document
↓
remove presentation and interface noise
↓
preserve meaningful content and context
↓
Markdown document

This is where manual maintenance becomes risky. A price changes, a policy is corrected, or an internal link moves, and somebody has to remember the second copy. Generate both representations from one source whenever possible.

Choose pages that are useful on their own

Do not mirror every URL merely because the site can generate it. Good candidates contain information that remains useful after the surrounding interface disappears:

• Tutorials, guides, reviews, articles, and knowledge-base entries usually have a clear title, a structured body, and enough information to stand on their own.
• Documentation, API references, and configuration instructions are the clearest use case. Coding assistants often need one exact procedure or parameter rather than the complete interface of the documentation site.
• Substantial product, service, policy, about, and FAQ pages can work when their value comes from the content rather than the layout around it.
• A homepage may be useful when it explains a product, organization, or project in detail. A homepage made mostly of visual cards and links offers little as a separate text document.

Search results, pagination, thin tag archives, author listings, and other collection views usually make poor standalone documents. They are navigational states, not resources an agent needs to read from beginning to end. A taxonomy page may deserve a Markdown version when it contains unique guidance, but the label “category” is not a reason by itself.

What the Markdown file should contain

A useful Markdown document keeps the structure needed to understand and reuse the content:

# How to build a static website

- URL: https://example.com/how-to-build-static-website/
- Published: 2026-08-14T10:00:00.000Z
- Updated: 2026-08-14T12:00:00.000Z
- Description: A practical guide to building and publishing a static website.
- Author: Jane Smith
- Tags: Static sites, Web development

Static websites have changed considerably...

Preserve headings, paragraphs, lists, links, quotations, useful image descriptions, tables, code blocks, and relevant document metadata. Remove repeated navigation, cookie UI, social controls, layout wrappers, and unrelated recommendations.

Ways to expose the Markdown version

No single discovery method has universal support. Current implementations use several approaches.

A predictable .md URL

/post/
→ /post.md

This is often the easiest option for a static site. The Markdown document is another file that ordinary hosting can cache and serve.

An alternate link from HTML

<link rel="alternate" type="text/markdown" href="https://example.com/post.md">

A client inspecting the HTML can find the alternate document without guessing its URL. Support varies, but the relationship is clear and inexpensive to publish.

Links from llms.txt

An llms.txt index can link directly to Markdown where it exists and keep HTML links for the rest of the site. This suits curated documentation and support collections better than an indiscriminate export of every URL.

HTTP content negotiation

GET /post/ HTTP/1.1
Host: example.com
Accept: text/markdown

Content negotiation keeps one public URL while changing the returned representation. It requires support from the application, server, or CDN. A separate file is usually easier for a static site generator.

SEO and indexing

Treat Markdown as an alternate representation, not a second SEO landing page. Keep the HTML URL as the primary document, with its existing title, meta description, canonical URL, robots settings, and structured data.

A Markdown file may include the original URL, publication and update dates, description, author, and tags. Those fields provide context to the reader of the file; they do not replace the SEO metadata on the HTML page.

Google can crawl and index text resources outside ordinary HTML pages, so a public .md file is not invisible. Additional URLs can also consume crawl resources on a very large site. I would keep Markdown alternatives out of the XML sitemap, carry over existing noindex decisions, and monitor Search Console after deployment.

Publii's Markdown for AI plugin follows that model. It leaves HTML SEO settings unchanged, does not add generated Markdown files to the sitemap, and excludes content marked noindex by default.

The maintenance cost decides whether it is worth doing

A manually maintained Markdown copy is difficult to recommend. Every correction has to be made twice, links drift, and metadata becomes stale. No measured visibility benefit is large or reliable enough to pay for that editorial overhead.

Automatic generation changes the decision because the author still edits one source. Documentation, technical blogs, knowledge bases, and other content-heavy sites can then offer Markdown with little ongoing work.

A small restaurant site or portfolio does not need it. Clear HTML remains accessible to search engines and AI tools, and there may be too little standalone content to justify another publishing layer. I would add Markdown only when the site has documents that agents are likely to retrieve and the build process can keep both representations synchronized.

How Publii generates Markdown

The Markdown for AI plugin generates companion files from the same source content used for the HTML site. Authors continue writing and updating posts in Publii; there is no second editorial workflow.

/post/             → /post.md
/post.html         → /post.md
/page/about/       → /page/about.md
/page/about.html   → /page/about.md

The plugin works with individual posts and pages rather than duplicating every URL. Tag listings, author listings, archives, pagination, 404 pages, and other collection views are excluded.

Generated files can preserve headings, paragraphs, lists, links, images, tables, quotations, and code blocks. They can also include the original HTML URL, publication and update dates, description, author, and tags. When generation succeeds, the HTML page can advertise its companion file:

<link rel="alternate" type="text/markdown" href="https://example.com/post.md">

The HTML page keeps its canonical URL, title, meta description, robots settings, and structured data. If a post later changes to noindex, Publii removes its generated Markdown counterpart during the next site generation and stops advertising the alternate file.

How Markdown for AI works with LLMS.txt Generator

Markdown for AI and LLMS.txt Generator work independently. When both are active, they detect each other automatically.

LLMS.txt Generator can prefer a Markdown link when the companion file exists:

## Guides

- [Installing Publii](https://example.com/install.md): Installation instructions
- [Creating a website](https://example.com/create-site.md): Getting started guide

The plugin checks the generated output before changing the destination. If Markdown was excluded, the page has noindex, or the file was not created for another reason, the entry keeps its HTML URL. One index can therefore contain both formats:

## Guides

- [Installing Publii](https://example.com/install.md): Installation instructions
- [About our project](https://example.com/about/): Learn more about the project

The connection also works in the other direction. A generated Markdown document can point back to the site's main index:

> ## Content Index
> Fetch the complete content index at: https://example.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Post title

No manual connection is required, and disabling either plugin does not stop the other from working. The integration maintains the relationship between an index and the documents it lists; it does not promise that an AI platform will crawl or cite the site more often.

My recommendation

I would publish Markdown alternatives for documentation, technical blogs, knowledge bases, and other content-heavy sites when the same build produces both formats. The evidence is good enough to support Markdown as a clean machine-readable representation, especially for coding agents and documentation workflows.

I would not create or maintain those copies by hand, and I would not sell the work internally as an SEO or AI-visibility shortcut. If the only goal is more citations, improve the HTML page instead. If an agent needs to retrieve and process the document, and automation keeps the copy current, Markdown has a job worth doing.