# "Host Did Not Return Markdown Content When Accept: text/markdown Was Requested" — What That Means And How To Fix It

Run the Agent Runtime Readiness audit and you may see this warning on the third test. It is the audit telling you AI runtimes are sending Accept: text/markdown to your URL and getting full HTML back instead of a slim markdown twin. Here is what the warning is actually testing, and the two fix paths — the Cloudflare toggle and the origin-side content negotiation pattern.

Author: J.A. Watte
Published: May 9, 2026
Source: https://jwatte.com/blog/blog-fix-markdown-for-agents-warning/

---

If you ran a URL through the [Agent Runtime Readiness](/tools/agent-runtime-readiness/) audit and the third check came back amber, you saw this exact line:

> Host did not return Markdown content when Accept: text/markdown was requested. Enable Cloudflare Markdown for Agents or implement content negotiation at your origin.

This post unpacks what the audit actually probed, why the warning is worth fixing rather than ignoring, and the two concrete paths to clear it.

## What the audit did

The audit sent your URL through its proxy twice. The first pass used the default `Accept: text/html` request that any browser sends. The second pass used `Accept: text/markdown` — the negotiation header that Cloudflare's Markdown for Agents feature listens for, and that AI runtimes have begun sending when they want a clean text twin of a page rather than a full HTML document.

For the second pass to count as a pass, the response had to either:

- carry a `Content-Type` header that contains the word `markdown`, or
- return a body that opens with a YAML frontmatter block or a leading `# ` heading and is materially shorter than the HTML response

If neither was true, your origin returned HTML to the markdown request. The audit recorded the third check as a warn (not a fail — the page is still readable, it just is not pre-formatted for retrievers) and emitted the message above.

## Why it matters

Cloudflare shipped Markdown for Agents on February 12, 2026 as a one-toggle feature on Pro and Business zones. Within a month, mainstream AI runtimes — OpenAI's Agents SDK, Cloudflare's own Project Think, several smaller MCP-style fetch tools — began including `text/markdown` in their Accept headers when retrieving an arbitrary URL. The payoff is straightforward: the markdown twin of a typical article page is roughly 80% smaller than the HTML, and a model can read it without the wrapper of nav, footer, sidebar, and ad markup that an HTML response carries. ([Cloudflare blog announcement](https://blog.cloudflare.com/markdown-for-agents/))

The bigger context is the [agent runtime shift covered in the runtime-as-the-new-browser post](/blog/blog-agent-runtime-the-new-browser-layer/) — runtimes, not models, are now what reads your site. A runtime that gets a clean markdown response can hand the model exactly the text the model needs and nothing else. A runtime that has to fall back to scraping HTML, stripping tags, and converting to text burns context window on the wrapper and may fail to extract the canonical content cleanly.

The warning is not telling you your site is broken. It is telling you that AI clients asking nicely for the slim version are not getting it.

## Fix path 1 — Cloudflare Markdown for Agents toggle

If your zone is on Cloudflare Pro or Business (the Free plan does not include this feature as of writing), the fastest fix is the dashboard toggle.

1. Sign into [dash.cloudflare.com](https://dash.cloudflare.com), open the zone, and go to the AI Crawl Control section.
2. Find the Markdown for Agents row and flip it on.
3. Wait roughly a minute for the change to propagate to the edge.
4. Re-run the [Agent Runtime Readiness audit](/tools/agent-runtime-readiness/) on the same URL. The third check should flip to a pass.

When the toggle is on, requests with `Accept: text/markdown` get a response with these headers:

```
Content-Type: text/markdown; charset=utf-8
Vary: Accept
Content-Signal: ai-train=yes, search=yes, ai-input=yes
```

The `Vary: Accept` header tells caches to treat the markdown and HTML responses as separate entries — your browser visitors keep getting HTML, your AI visitors get markdown, and CDN caching does not collide between the two. The `Content-Signal` header is Cloudflare's default declaration that the markdown response is allowed for AI training, search indexing, and live AI input. If you want to restrict any of those, you can override the default per-zone or per-route. ([Cloudflare Fundamentals docs on Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/))

The conversion happens at Cloudflare's edge, not at your origin. You write zero code. The downside is that the conversion is generic — Cloudflare's HTML-to-markdown logic decides what is content and what is wrapper. If your page has unusual layout patterns that confuse a generic converter, the markdown twin may include stray nav text or miss part of the article. Spot-check the output at least once after enabling.

## Fix path 2 — Origin content negotiation

If you are not on Cloudflare, are on the Free plan, or want full control over what the markdown twin looks like, implement content negotiation at your origin. Two patterns work:

**Pattern A, runtime conversion.** Your server inspects the `Accept` header on every request. If it includes `text/markdown` and not `text/html`, return a markdown rendering of the page instead of the HTML one. Most static-site generators (Eleventy, Hugo, Astro, Next.js) keep the source markdown around — serve it directly with the right Content-Type. For a CMS, the simplest implementation is a middleware that runs your HTML response through a converter (turndown for Node, html2text for Python, html-to-md for Go) and rewrites the response.

**Pattern B, companion files.** Publish a `.md` companion at every URL — `/blog/foo/` becomes `/blog/foo/index.md`, or `/blog/foo` becomes `/blog/foo.md`. Then add a redirect or rewrite rule that intercepts `Accept: text/markdown` and serves the companion file instead. This is what some sites do because it lets the markdown be statically cached and CDN-distributed. The downside is that you have to keep two versions of every page in sync; if the HTML drifts from the markdown, retrievers get a stale answer.

In either pattern, set these response headers:

```
Content-Type: text/markdown; charset=utf-8
Vary: Accept
```

The `Vary: Accept` header is not optional. Without it, an upstream cache may serve your markdown response to a browser visitor who asked for HTML, breaking the page. Set it on every markdown response.

A passive-declaration variant exists too: add `<link rel="alternate" type="text/markdown" href="/path/to/page.md">` to your HTML head. This does not satisfy the audit's negotiation check (the audit verifies that the host actually responds with markdown, not that it advertises one), but it is a useful breadcrumb for retrievers that want to find the markdown twin without sending the negotiation header. The Mega Analyzer audit on this site picks up that `<link rel="alternate">` declaration as a separate signal.

## Which fix to pick

If you are on Cloudflare Pro or Business: flip the toggle. Five-minute fix, no code, no maintenance burden. Spot-check one or two pages and move on.

If you are on Cloudflare Free or another host and your content is mostly markdown-source-compatible (a Hugo or Eleventy site where the source files are already markdown): origin negotiation, Pattern B with companion files. The companion is the same file you already have. You add one rewrite rule.

If you are on a CMS (WordPress, Ghost, Drupal) where the source is not markdown: origin negotiation, Pattern A with runtime conversion. Most modern CMS platforms have a markdown-export plugin or filter; wire it to the `Accept` header.

If your traffic is small and AI-runtime traffic is currently negligible: ignore the warning for now. The audit's third check is a warn, not a fail. Your page is still readable by every runtime that exists. The fix becomes more valuable as runtime traffic grows; track your access logs for `Accept: text/markdown` headers and prioritize accordingly.

## Verifying the fix

After applying either fix, two checks confirm it landed correctly:

1. **Re-run the Agent Runtime Readiness audit** on the same URL. Third check should be green.
2. **Confirm with curl** from any terminal: `curl -s -H "Accept: text/markdown" -i https://yourdomain.com/your-page/ | head -20`. The response should show `Content-Type: text/markdown; charset=utf-8`, a `Vary: Accept` header, and a markdown body in the first lines.

If the audit still warns after a confirmed-working curl response, the issue is usually one of:

- A CDN layer above your origin (the rewrite happens at origin but the CDN serves a cached HTML response to the audit's request)
- A `Vary: Accept` header missing from the markdown response (the cache is not differentiating by Accept header and is collapsing the two responses into one)
- The audit's proxy adding `Accept: text/html, application/xhtml+xml, */*` and your negotiation logic deferring to HTML when both are present

The third one is the most common false negative. Match `text/markdown` first regardless of what other Accept tokens are present, not "only when text/markdown is the sole accepted type."

## How this fits the larger runtime-readability picture

The Agent Runtime Readiness audit checks three things — server-rendered content ratio, inline JSON-LD presence, and Markdown for Agents content negotiation. The first two address whether a runtime that does not execute JavaScript can read your page at all. The third addresses whether the runtime gets a clean text version when one is offered. All three are part of the same shift: AI runtimes are the new browser layer, and your site has to be legible to them, not just to a human in Chrome.

If you want the deeper context on why this layer matters now, the post on [agent runtime as the new browser layer](/blog/blog-agent-runtime-the-new-browser-layer/) walks through the April 2026 announcements (Cloudflare Project Think, OpenAI Agents SDK) that pushed the runtime layer to the foreground. If you want the companion piece that introduces the audit itself, see [three tests every page has to pass for an AI agent runtime](/blog/blog-tool-agent-runtime-readiness/). And if you want to fix the related Cloudflare-side eligibility problem (where bot traffic is challenged before it ever reaches your origin), the [Cloudflare AI cache rule generator](/tools/cloudflare-ai-cache-rule-generator/) emits the cache and bot-rule configs that let verified AI bots through without being challenged.

## Related reading

- [Three Tests Every Page Has To Pass For An AI Agent Runtime](/blog/blog-tool-agent-runtime-readiness/) — the audit itself, all three checks explained
- [The Conversation Has Moved Past The Model](/blog/blog-agent-runtime-the-new-browser-layer/) — why the runtime layer matters
- [Your Site Might Be Invisible To ChatGPT](/blog/blog-499-ai-search-eligibility-cloudflare/) — the Cloudflare 499-timeout eligibility problem
- [Markdown Memory Beats Vector Database](/blog/blog-markdown-memory-beats-vector-database/) — why markdown-as-source-of-truth is winning the agent context battle
- [Why Most AI Crawlers Cannot Read Your Site](/blog/blog-cloudflare-ai-crawler-allowlist/) — the allowlist side of the runtime-readability stack

## Fact-check notes and sources

- Cloudflare Markdown for Agents announcement (February 12, 2026): [blog.cloudflare.com/markdown-for-agents/](https://blog.cloudflare.com/markdown-for-agents/)
- Cloudflare Fundamentals reference docs: [developers.cloudflare.com/fundamentals/reference/markdown-for-agents/](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/)
- Cloudflare changelog entry: [developers.cloudflare.com/changelog/post/2026-02-12-markdown-for-agents/](https://developers.cloudflare.com/changelog/post/2026-02-12-markdown-for-agents/)
- Search Engine Journal coverage of the launch: [searchenginejournal.com/cloudflares-new-markdown-for-ai-bots-what-you-need-to-know](https://www.searchenginejournal.com/cloudflares-new-markdown-for-ai-bots-what-you-need-to-know/567339/)
- The New Stack technical write-up: [thenewstack.io/cloudflares-markdown-for-agents-automatically-make-websites-more-aifriendly/](https://thenewstack.io/cloudflares-markdown-for-agents-automatically-make-websites-more-aifriendly/)
- The Vary header semantics that make content negotiation safe to cache are specified in [RFC 9110 §12.5.5](https://www.rfc-editor.org/rfc/rfc9110#field.vary)

If you want the full map of how this kind of audit fits into a build-your-own-web stance — owning the surface, the data, and the audit loop end to end — *The $20 Dollar Agency* covers the operating model behind running these audits as a small-team service offering.

*This post is informational, not legal or SEO-consulting advice. Cloudflare and OpenAI references are nominative fair use; no affiliation is implied.*


---

Canonical HTML: https://jwatte.com/blog/blog-fix-markdown-for-agents-warning/
RSS: https://jwatte.com/feed.xml
JSON Feed: https://jwatte.com/feed.json
Hero image: https://jwatte.com/images/blog-fix-markdown-for-agents-warning.webp