Markdown for AI agents: serve product pages as text/markdown

Why it matters for AI agents

AI agents that read pages as text have to strip HTML first. On a typical product page, most of the bytes are layout, scripts and tracking, and the facts an agent needs, such as name, price, availability, options and return policy, are a small fraction. Cloudflare estimates Markdown uses about 80% fewer tokens than the equivalent HTML (Cloudflare blog).

There are two ways to offer it:

• Content negotiation: the client sends Accept: text/markdown, and the server answers with Content-Type: text/markdown and Vary: Accept (Cloudflare Markdown for Agents).
• A Markdown URL linked from the HTML head with <link rel="alternate" type="text/markdown">, often the page URL plus .md, as suggested by the llms.txt proposal.

Adoption is still low. Cloudflare’s Agent Readiness research found 3.9% of sites support negotiation, and in our calibration only 2 of 31 stores passed. That is why this check carries the lowest weight in the Discovery category.

What the scanner checks

The scanner tests the first sampled product page, or the homepage if no product page loaded. It re-requests that URL with Accept: text/markdown, text/html;q=0.9 and inspects the response. It also looks for a rel="alternate" type="text/markdown" link in the HTML head or the Link response header (it does not fetch the linked file).

Result	When
Pass	The negotiated request returns a successful response with a text/markdown content type
Partial	Negotiation returns HTML, but a Markdown alternate is linked
Fail	Negotiation returns HTML and no alternate is linked, or the Accept: text/markdown request breaks the page (an error status, including a redirect that ends in 404)
Inconclusive	No page loaded to test

A broken response is the worst outcome: an agent that asks for Markdown gets nothing, when plain HTML would at least have worked.

How to fix it

1. Decide what goes in the Markdown version. For a product page: name, price and currency, availability, options, description, and links to shipping and returns.

# Merino Crew Sock

**Price:** $18.00 USD · **Availability:** In stock
**Sizes:** S, M, L · **Colors:** Navy, Charcoal

Midweight merino wool sock with a cushioned sole.

- [Shipping](https://shop.example.com/pages/shipping)
- [Returns](https://shop.example.com/pages/returns)

2. When the request’s Accept header prefers text/markdown, return that rendering with these headers:

HTTP/2 200
Content-Type: text/markdown; charset=utf-8
Vary: Accept

Vary: Accept stops caches from serving Markdown to browsers or HTML to agents.

3. Publish the same content at a stable URL (for example /products/merino-crew-sock.md) and link it:

<link rel="alternate" type="text/markdown" href="/products/merino-crew-sock.md" />

4. If you are on Cloudflare Pro or higher, you can enable Markdown for Agents instead of building the conversion yourself.
5. Verify:

curl -sI -H "Accept: text/markdown" https://shop.example.com/products/merino-crew-sock | grep -i content-type
# content-type: text/markdown; charset=utf-8

Common mistakes

• Missing Vary: Accept, so a CDN caches the Markdown and serves it to human visitors.
• Redirect rules that key on the Accept header and send unknown types to an error page.
• Markdown that drops the price or availability, so the agent still has to fetch the HTML.

How to fix it on Medusa

Medusa’s DTC starter storefront does not serve Markdown, but you can add it in the Next.js app:

• Add a route handler that fetches the product from the Store API and returns it as text/markdown, with Vary: Accept.
• In middleware, rewrite product requests whose Accept header prefers text/markdown to that handler, and link the Markdown URL with alternates.types in generateMetadata (Next.js metadata).

Medusa’s own documentation works this way: docs pages return Markdown for Accept: text/markdown or a .md URL (Medusa AI-friendly docs).

Sources

• Cloudflare: Markdown for Agents
• Cloudflare blog: Markdown for Agents
• Cloudflare blog: Agent Readiness score
• llms.txt proposal (.md page versions)
• MDN: Vary header
• Medusa: AI-friendly docs