Cloudflare Markdown for Agents

Markdown for Agents is a content-negotiation standard from Cloudflare: an agent or crawler can ask for a pre-processed Markdown version of a page instead of raw HTML. That cuts token usage and parsing overhead for the model reading it.

The problem: HTML is expensive to read

Web pages are built for browsers, not language models. The cost shows up in three ways:

• Token waste — ## About Us is about 3 tokens; the same heading as <h2 class="section-title" id="about">About Us</h2> is 12–15.
• Noise — <div> wrappers, scripts, and navigation fill the context window without adding meaning.
• Impact — converting a page from HTML to Markdown typically yields around an 80% reduction in tokens.

How it works: content negotiation

The feature rides on standard HTTP content negotiation. The agent states its preference with the Accept header.

Request — include text/markdown:

curl https://blog.cloudflare.com/markdown-for-agents/ \
  -H "Accept: text/markdown"

From a Worker — prefer Markdown, fall back to HTML:

const r = await fetch(
  `https://target-url.com/`,
  {
    headers: {
      Accept: "text/markdown, text/html",
    },
  },
);

Response headers carry the content plus useful metadata:

Content Signals

The Content-Signal header lets a publisher declare how AI systems may use its content:

Content-Signal: ai-train=yes, search=yes, ai-input=yes

• ai-train — may be used for model training.
• search — may be indexed for search (including RAG).
• ai-input — may be used as direct input to an agentic workflow, e.g. summarization.

When a source doesn’t support it

For pages without native Markdown negotiation, Cloudflare offers conversion APIs:

• Workers AI — AI.toMarkdown() converts and summarizes various document types.
• Browser Rendering — the /markdown REST API renders JavaScript-heavy pages in a headless browser first, then converts them.

Adoption

• Native support — Claude Code and OpenCode send Accept: text/markdown automatically.
• CMS — the Markdown Alternate plugin for WordPress serves rich, metadata-aware Markdown at dedicated URLs, complementing edge conversion.
• Edge alternatives — services like Fasterize EdgeSEO offer similar dynamic HTML-to-Markdown conversion for bots without requiring Cloudflare.

Beyond retrieval: Markdown as an orchestration language

Token efficiency is only half the story. Because agents read Markdown natively, structured Markdown has become a way to instruct and constrain agents, not just feed them content.

The clearest example is gstack, from Y Combinator CEO Garry Tan, which uses a collection of Markdown files as skills and operational boundaries for Claude Code. Unconstrained models tend to drift — executing an isolated instruction while losing the wider architectural context. Feeding an agent tightly structured Markdown that defines explicit roles (Product Manager, QA, DevOps) forces it into a defined persona and keeps multi-step workflows coherent and aligned with the project’s goals.