Cloudflare Markdown for Agents: Headers & SEO 2026
Cloudflare's Markdown for Agents is easy to misunderstand if you approach it as another Markdown editor or converter. It is neither. The feature adds an HTTP content-negotiation path at the edge: an AI system sends Accept: text/markdown, and an enabled Cloudflare zone converts the origin's HTML into structured Markdown before returning it. A browser that asks for HTML still gets HTML.
That makes this a useful companion to md2rich, not a competitor. Markdown for Agents moves content from a site toward an agent. md2rich moves a writer's Markdown draft toward a publishing platform. The difference matters for SEO, caching, security headers, and the privacy-first workflow behind this site.
Cloudflare's July 13, 2026 changelog is the reason to revisit the feature now: converted responses preserve security- and cache-relevant headers, respect the origin's Content Signals policy, and fix relative-link resolution for directory-style URLs. Here is what publishers should actually test.
What Markdown for Agents actually does
The feature is an edge representation of an existing page. Your origin remains the source of truth. If a client requests a normal HTML representation, Cloudflare serves the normal page. If the client includes text/markdown in its Accept header, Cloudflare fetches the HTML, strips non-content elements, and returns Markdown when conversion is possible.
The documented output has three parts:
- YAML frontmatter extracted from supported title, description, and Open Graph tags.
- Body Markdown converted from the page body, with navigation, scripts, styles, headers, and footers removed.
- JSON-LD preserved at the end in a fenced
jsonblock, so structured data is not lost during conversion.
This is useful because agents do not have to invent a bespoke HTML parser for every site. They can request a predictable text representation, retain page metadata, and still inspect schema markup. It is an interoperability layer, not a new authoring surface.
The request is ordinary HTTP content negotiation
Cloudflare's official documentation shows the smallest possible client:
curl https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/ \
-H "Accept: text/markdown"An agent can do the same thing from JavaScript. The response includes token estimates that can help an agent decide whether a page fits its context window or how aggressively to chunk it:
const response = await fetch(url, {
headers: { Accept: "text/markdown" },
});
const markdown = await response.text();
const markdownTokens = response.headers.get("x-markdown-tokens");
const originalTokens = response.headers.get("x-original-tokens");The important operational detail is Vary: Accept. HTML and Markdown are two representations of one URL. A cache that ignores the Accept dimension could serve Markdown to a browser or HTML to an agent. Cloudflare documents that the converted response adds Accept to Vary, while preserving any other origin-declared dimensions.
Headers: what survives, what changes, and why
The July 13 changelog makes Markdown for Agents much more practical for production sites. Converting the body does not mean discarding the response's security and caching policy.
| Header group | Documented behavior | Publisher implication |
|---|---|---|
| Security | HSTS, CSP, X-Frame-Options, Set-Cookie, and CORS headers are preserved. | The Markdown representation keeps the origin's security posture. |
| Caching | Cache-Control, Expires, and Age continue to pass through. | Agents can receive a cacheable representation without losing cache intent. |
| Representation | Content-Type becomes text/markdown; Content-Length is recalculated. | Clients can trust the body type and length for the new response. |
| Cache key | Vary includes Accept. | HTML and Markdown variants stay distinct in a compliant cache. |
| Original body metadata | ETag, Last-Modified, Content-Encoding, Content-Range, and Transfer-Encoding are removed. | Do not build conditional-request logic around the converted body. |
The last row is easy to miss. A converted body is not byte-identical to the origin body, so an origin ETag or Last-Modified value would describe the wrong representation. Cloudflare drops those headers instead of pretending the old validators still apply.
Content Signals are the policy layer
Content Signals is the part most relevant to publishers thinking about AI crawlers. Cloudflare's docs say that an origin-provided content-signal header is authoritative and is preserved in the converted response. If the origin sends no policy, Cloudflare documents this default:
Content-Signal: ai-train=yes, search=yes, ai-input=yesThose values express three separate permissions: training use, search use, and AI input use, including agentic use. The practical takeaway is not that Cloudflare has decided your policy for you. It is that your origin can state the policy once, and the Markdown representation will carry it forward.
If you run a static site, treat this as a header-level publishing decision. Decide whether you want an agent to use your content as input, whether search discovery is allowed, and whether training use is allowed. Then test the actual response instead of relying on a dashboard screenshot or a robots file.
Does it change SEO or canonical URLs?
Not in the way a second HTML page would. Markdown for Agents uses content negotiation on the same URL. Normal users and search crawlers that request HTML see your canonical tag, visible page, and normal HTML metadata. An agent that asks for Markdown receives a different representation of that URL.
There are still SEO details worth checking:
- Keep a useful HTML
<title>, description, and Open Graph title because they seed the Markdown frontmatter. - Keep JSON-LD valid. Cloudflare preserves it, but malformed schema remains malformed after conversion.
- Use stable absolute or directory-correct relative links. The July 13 release fixed a trailing-slash resolution bug, but your links still need to be intentional.
- Keep the human page readable. Markdown output is an additional representation, not a reason to strip headings or context from the HTML.
In other words, this is closer to a structured distribution channel than a new indexable URL. You should measure it as part of your AI-search and agent-access strategy, while continuing to optimize the HTML that search engines render and users read.
How to enable it on a Cloudflare zone
Cloudflare documents Markdown for Agents for Pro, Business, and Enterprise plans, plus SSL for SaaS customers, at no additional cost. In the dashboard, select a zone, open the AI Crawl Control section, and enable Markdown for Agents. For a narrower rollout, use a Configuration Rule to match a hostname or path.
The documented API setting is a zone settings update:
curl -X PATCH \
"https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/content_converter" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer *** " \
--data '{"value":"on"}'Replace the placeholder with the real zone ID. Replace ZONE_ID and YOUR_API_TOKEN with your real credentials in your own command. For path-based control, Cloudflare's Configuration Rules documentation shows a content_converter setting that can be enabled when an expression such as starts_with(http.request.uri.path, "/blog/") matches.
Start with a small path or staging hostname if your site has sensitive content. Then test both representations with a clean cache and a real browser-like request.
A production test checklist for static-site publishers
- Fetch the page without an
Acceptoverride and confirm you still receivetext/html. - Fetch the same URL with
Accept: text/markdownand check fortext/markdownplus a Markdown body. - Confirm
VaryincludesAccept, and that your CDN does not collapse the two variants. - Check
Content-Signal, HSTS, CSP, CORS, and cache headers against your origin policy. - Check that frontmatter includes the title and description you intended, not a stale Open Graph fallback.
- Parse the JSON-LD code block and confirm that Article, BreadcrumbList, and FAQPage data remain valid.
- Test a page with a trailing slash and links such as
../page/; verify that the converted links resolve to the intended URLs. - Test a page over the documented 2 MB origin-response limit. Large pages may need to be split or simplified.
# HTML representation
curl -sSI https://example.com/blog/post/ \
-H "Accept: text/html" \
-H "Cache-Control: no-cache"
# Markdown representation
curl -sSI https://example.com/blog/post/ \
-H "Accept: text/markdown" \
-H "Cache-Control: no-cache"
# Inspect the converted body
curl -s https://example.com/blog/post/ \
-H "Accept: text/markdown" | head -80Do not call a successful HTTP 200 proof of success. The useful evidence is the representation, headers, title/frontmatter, links, and schema together.
Markdown for Agents versus md2rich
The names overlap because both products care about Markdown, but their directions are opposite:
| Question | Markdown for Agents | md2rich |
|---|---|---|
| Who uses it? | AI agents, crawlers, and structured-content clients. | Human writers publishing a Markdown draft. |
| Direction | Hosted HTML → Markdown. | Markdown → rich text. |
| Where does it run? | At Cloudflare's edge for an enabled zone. | In the browser via client-side JavaScript. |
| What leaves the device? | The request reaches the hosted site and Cloudflare edge. | The draft is not uploaded to a conversion server. |
| Primary output | Predictable Markdown with frontmatter and preserved JSON-LD. | Clipboard-ready rich text for LinkedIn, X, Medium, Notion, and Substack. |
A real workflow can use both. An agent requests a research page as Markdown, a writer edits and fact-checks the draft in a local editor, and md2rich converts the finished Markdown to the rich text a publishing platform expects.
Two Markdown-to-rich-text examples
Cloudflare's feature helps an agent read your published page. At the publishing end, the writer still needs a clean way to turn Markdown into platform-friendly rich text. Here are two small examples of what that handoff looks like.
Example 1: a short announcement
## The useful update
Cloudflare now preserves **Content Signals** in Markdown responses.
- Check your headers
- Test both representations
- Keep the Markdown sourcePaste that source into md2rich, click Copy as Rich Text, and the destination receives a heading, paragraph with bold emphasis, and a real list instead of literal Markdown punctuation. The source stays reusable for a blog post, LinkedIn article, or X Article.
Example 2: a code-focused tutorial
### Test the Markdown variant
```bash
curl https://example.com/post/ -H "Accept: text/markdown"
```
> Verify `Vary: Accept` before shipping.The same draft becomes a styled subheading, a readable code block, and a blockquote with inline code when copied as rich text. That is the narrow job md2rich is built for: preserve the author's structure while moving it into a platform that does not accept raw Markdown paste reliably.
For the earlier Cloudflare comparison — Workers AI's document conversion versus md2rich's writer-facing workflow — see Cloudflare Workers AI toMarkdown vs md2rich. For the broader crawler-policy context, see our Cloudflare Content Independence Day guide.
What we verified on md2rich.com
This article is published on a static site, so it is worth checking the claim rather than assuming that every Cloudflare-hosted site has the feature enabled. On July 19, 2026, a live request to md2rich.com with Accept: text/markdown still returned text/html. That means this site is not currently advertising a Markdown representation through that setting, even though the zone could support it if the feature is enabled and configured.
That distinction is useful for operators: being on Cloudflare is not the same as having Markdown for Agents enabled. Test the response. If your site uses a custom cache, WAF, or configuration rule, test those layers too. A page can have excellent HTML SEO and still return the wrong representation, stale metadata, or collapsed cache variants to agents.
The practical verdict for 2026
Markdown for Agents is a sensible protocol improvement for the agent web. It gives clients an explicit way to ask for structured text, preserves the metadata and schema that make pages understandable, carries forward the origin's security and cache policy, and makes Content Signals operational instead of purely declarative documentation.
It is not a replacement for writing in Markdown, and it is not a replacement for a Markdown-to-rich-text publishing tool. The clean stack is layered:
- Write once in Markdown so your source is portable.
- Publish with a client-side converter when the destination expects rich text; try md2rich for that step.
- Expose the published page to agents as Markdown when your Cloudflare policy and audience call for it.
- Verify headers and policy with real HTTP requests, not assumptions.
The most important mindset shift is simple: a web page no longer has to be one representation. Human readers can get HTML, agents can request Markdown, and the origin can still declare how the content should be used. Treat those paths as part of one publishing system and test them together.
Frequently asked questions
Does Markdown for Agents create a new URL?
No. It uses the same URL with the HTTP Accept header to negotiate the response representation. The HTML and Markdown variants should be kept separate in caches through Vary: Accept.
Does it preserve JSON-LD?
Yes. Cloudflare documents that JSON-LD scripts are preserved in a fenced JSON block at the end of the Markdown response. Validate the original JSON-LD first; conversion does not repair broken schema.
Does it work on every Cloudflare plan?
Cloudflare's documentation lists Pro, Business, Enterprise, and SSL for SaaS availability. Check the current plan documentation before designing around it.
Is this the same as Workers AI document conversion?
No. Markdown for Agents converts HTML at the edge through content negotiation. Workers AI conversion APIs target application workflows and can support other document types. They solve different operational problems.
Should every blog enable it?
No. Decide based on your audience, content policy, and agent-access goals. If you enable it, test privacy-sensitive paths, Content Signals, caching, metadata, links, and schema before making it a default.
Try md2rich — client-side Markdown to rich text
Open the md2rich editor in any browser, paste Markdown, click Copy as Rich Text, and paste into LinkedIn, X Articles, Medium, Notion, or Substack. No upload, no account, no API key — your draft stays in the browser.