# Markdown for AI agents: serve product pages as text/markdown
> A Markdown alternative is a plain-text version of a page served when a client sends Accept: text/markdown, or linked with rel=alternate type=text/markdown. It gives AI agents product name, price and options without HTML noise, using far fewer tokens. It is an emerging, low-weight signal.
- Source: https://is-agentic-storefront.com/checks/markdown-alternative
- Updated: 2026-10-15
- Category: Discovery (15% of score)
- Impact: Low
- Spec: [Cloudflare Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents)
- Scanner check: Markdown version of pages for agents
## 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](https://blog.cloudflare.com/markdown-for-agents/)).
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](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents)).
- **A Markdown URL** linked from the HTML head with ``, often the page URL plus `.md`, as suggested by the [llms.txt proposal](https://llmstxt.org/).
Adoption is still low. Cloudflare's [Agent Readiness](https://blog.cloudflare.com/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.
```markdown
# 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
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:
```html
```
4. If you are on Cloudflare Pro or higher, you can enable Markdown for Agents instead of building the conversion yourself.
5. Verify:
```sh
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](https://github.com/medusajs/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](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#alternates)).
Medusa's own documentation works this way: docs pages return Markdown for `Accept: text/markdown` or a `.md` URL ([Medusa AI-friendly docs](https://docs.medusajs.com/learn/introduction/build-with-llms-ai/ai-friendly-docs)).
## Sources
- [Cloudflare: Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents)
- [Cloudflare blog: Markdown for Agents](https://blog.cloudflare.com/markdown-for-agents/)
- [Cloudflare blog: Agent Readiness score](https://blog.cloudflare.com/agent-readiness/)
- [llms.txt proposal (.md page versions)](https://llmstxt.org/)
- [MDN: Vary header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Vary)
- [Medusa: AI-friendly docs](https://docs.medusajs.com/learn/introduction/build-with-llms-ai/ai-friendly-docs)
## Frequently asked questions
### Do AI agents request Markdown with Accept: text/markdown?
Some agent tools do, but OpenAI, Anthropic and Google do not officially document sending that header. Treat Markdown support as a low-cost bonus, not a requirement.
### How do I serve Markdown versions of my pages on Cloudflare?
Cloudflare's Markdown for Agents feature, available on Pro plans and higher, converts HTML to Markdown at the edge when a request asks for text/markdown. You can also build it yourself in your app or a Worker.
### Can serving Markdown break my store?
Yes, if a server, CDN or redirect rule mishandles the Accept header. A request with Accept: text/markdown must still get either Markdown or the normal HTML page, never an error or a redirect to a 404.
## Run your store on a platform built for agentic commerce
Medusa is open-source, headless commerce with a full Store API agents can call and storefronts you control end to end.
### Deploy on Medusa Cloud
Open-source commerce with a full Store API, hosted and scaled for you. Your storefront, your data model.
- [Deploy on Medusa Cloud](https://cloud.medusajs.com?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Fmarkdown-alternative)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Fmarkdown-alternative)
### Storefront skills for coding agents
Teach Claude Code, Cursor or Codex to build storefronts with the patterns these checks look for.
```bash
npx skills add medusajs/medusa-agent-skills
```
[View the skill on GitHub](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)
---
Scan your store for free at https://is-agentic-storefront.com/