Knowledge Base
---
title: "Cloudflare Markdown for Agents"
id: "kb/AI/2_agents/standards/01_cloudflare-markdown-for-agents"
version: "1.1"
steward: "Adam Bernard"
updated: "2026-03-23"
status: "Active"
doc_type: "Reference"
summary: "Technical reference for Cloudflare's 'Markdown for Agents' feature, and the broader evolution of Markdown as a first-class programming language for agentic workflows."
tags:
- "cloudflare"
- "web-scraping"
- "token-optimization"
- "standards"
- "http"
- "agentic-coding"
- "gstack"
relations:
- "kb/AI/3_methods/mcp/15_google-developer-knowledge-api-mcp"
- "kb/AI/3_methods/mcp/16_practical-local-mcp-use-cases"
- "kb/AI/3_methods/18_agentic-markdown-programming"
aliases:
- "Markdown Content Negotiation"
- "Content Signals"
- "Agentic Markdown"
# --- AI & RAG Enhancement ---
semantic_summary: "Cloudflare's 'Markdown for Agents' enables AI systems to request content in Markdown format using the 'Accept: text/markdown' HTTP header, reducing token consumption by 80%. Beyond content retrieval, Markdown has evolved into a first-class programming language for orchestrating AI agents, as demonstrated by frameworks like gstack which use Markdown to define rigid operational roles for Claude Code."
synthetic_questions:
- "How do I request Markdown from Cloudflare-enabled sites?"
- "What is the token saving of Markdown vs HTML for agents?"
- "What are Content Signals in HTTP headers?"
- "How is Markdown used as a programming language for AI agents?"
- "What is the gstack framework?"
key_concepts:
- "Content Negotiation"
- "Token Optimization"
- "Content Signals"
- "Accept Header"
- "Agentic Markdown"
- "gstack"
# --- SEO & Publication ---
primary_keyword: "Markdown for Agents"
seo_title: "Markdown for Agents: HTTP Content Negotiation & Agentic Coding"
meta_description: "Technical guide to Cloudflare's Markdown for Agents and the evolution of Markdown as a first-class programming language for AI workflows like gstack."
excerpt: "Reduce AI token costs by 80% using Cloudflare's Markdown for Agents, and discover how Markdown is evolving into a programming language for AI orchestration."
cover_image: ""
---
# Cloudflare Markdown for Agents
**Markdown for Agents** is a content negotiation standard implemented by Cloudflare that allows AI agents and crawlers to request a pre-processed Markdown version of a webpage instead of raw HTML. This significantly reduces token usage and parsing complexity for Large Language Models (LLMs).
## 1. The Problem: HTML Token Bloat
Standard web pages are optimized for visual rendering, not semantic processing.
* **Token Inefficiency:** A simple header like `## About Us` (3 tokens) becomes `<h2 class="section-title" id="about">About Us</h2>` (12-15 tokens) in HTML.
* **Noise:** `<div>` wrappers, scripts, and navigation bars consume context window space without adding semantic value.
* **Impact:** Converting HTML to Markdown typically yields an **80% reduction** in token usage.
## 2. Implementation: Content Negotiation
The feature utilizes standard HTTP Content Negotiation. Agents express their preference for Markdown using the `Accept` header.
### 2.1 Request Format
To fetch the Markdown version of a supported page, the client must include `text/markdown` in the header.
**cURL Example:**
```bash
curl https://blog.cloudflare.com/markdown-for-agents/ \
-H "Accept: text/markdown"
TypeScript/Worker Example:
const r = await fetch(
`https://target-url.com/`,
{
headers: {
Accept: "text/markdown, text/html", // Prefer markdown, fallback to HTML
},
},
);
2.2 Response Headers
The server responds with the Markdown content and specific metadata headers:
| Header | Description |
|---|---|
content-type |
text/markdown; charset=utf-8 |
x-markdown-tokens |
Estimated number of tokens in the returned document. Useful for context window budgeting. |
content-signal |
Permissions for AI usage (see Section 3). |
3. Content Signals
Cloudflare includes a Content-Signal header to explicitly state how the content provider permits their data to be used by AI systems.
Example Header:
Content-Signal: ai-train=yes, search=yes, ai-input=yes
- ai-train: Can be used for model training.
- search: Can be used for search indexing (RAG).
- ai-input: Can be used as direct input for an agentic workflow (e.g., summarization).
4. Alternative Conversion Methods
If a source does not support native Markdown negotiation, Cloudflare provides alternative APIs for developers:
- Workers AI:
AI.toMarkdown()supports summarization and conversion of various document types. - Browser Rendering: The
/markdownREST API can render dynamic JavaScript-heavy pages in a headless browser before converting them to Markdown.
5. Ecosystem & Adoption
As of early 2026, major agentic frameworks have adopted this standard:
- Native Support: Claude Code and OpenCode automatically send
Accept: text/markdownheaders. - CMS Integrations: The Markdown Alternate plugin for WordPress allows site owners to serve rich, metadata-aware markdown at dedicated URLs, complementing Cloudflare’s edge conversion.
- Edge Alternatives: Services like Fasterize EdgeSEO offer similar dynamic HTML-to-Markdown conversion for bots without requiring Cloudflare’s specific infrastructure.
6. Beyond Content: Markdown as an Agentic Programming Language
The push for Markdown optimization extends far beyond web scraping and token efficiency. Markdown has fundamentally evolved from a lightweight formatting syntax into a first-class programming language used to instruct, constrain, and orchestrate autonomous AI agents [1]
Because AI agents read Markdown natively, structured text has become the universal compiler instruction set for generative AI. This paradigm shift is most prominently demonstrated by frameworks like gstack, created by Y Combinator CEO Garry Tan. The gstack repository utilizes a collection of Markdown files to operate as specific skills and operational boundaries for Claude Code [1]
Unconstrained large language models often suffer from “mushy mode”—executing isolated instructions while losing sight of broader architectural context. Agentic Markdown solves this by forcing the model into rigidly defined personas [1] By feeding an agent highly structured Markdown files, system architects can define explicit roles (such as Product Manager, QA, or DevOps), ensuring that multi-step development workflows remain coherent and aligned with overarching project goals.
