Markdown for Agents

Markdown は、エージェントや AI システム全体の共通言語として急速に広がりました。明示的な構造があるため AI の処理に向き、結果の質を上げつつトークンの浪費を抑えられます。

Cloudflare のネットワークは、有効化済みゾーンに対して コンテンツネゴシエーション ↗ ヘッダーを使い、送信元でリアルタイムにコンテンツを変換します。Cloudflare を利用し、Markdown for Agents が有効なウェブサイトから AI システムがページを取得するとき、リクエストで text/markdown を優先できます。可能な場合、ネットワークは HTML をその場で効率よく Markdown に変換します。

詳細はブログの 発表記事 ↗ を参照してください。

Markdown for Agents が有効なゾーンの任意のページを Markdown 版として取得するには、クライアントが Accept ネゴシエーションヘッダーに text/markdown を含めます。Cloudflare はこれを検出し、オリジンから元の HTML を取得して、クライアントへ返す前に Markdown へ変換します。

開発者ドキュメントのこのページを、Accept ネゴシエーションヘッダー付きで取得する curl の例です。

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

Workers で AI Agent を構築している場合は、TypeScript を使えます。

const r = await fetch(
	`https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/`,
	{
		headers: {
			Accept: "text/markdown",
		},
	},
);
const tokenCount = r.headers.get("x-markdown-tokens");
const originalTokenCount = r.headers.get("x-original-tokens");
const markdown = await r.text();

const r = await fetch(
	`https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/`,
	{
		headers: {
			Accept: "text/markdown",
		},
	},
);
const tokenCount = r.headers.get("x-markdown-tokens");
const originalTokenCount = r.headers.get("x-original-tokens");
const markdown = await r.text();

このリクエストのレスポンスは、Markdown 形式になります。

HTTP/2 200
date: Wed, 11 Feb 2026 11:44:48 GMT
content-type: text/markdown; charset=utf-8
content-length: 2899
vary: accept
cache-control: public, max-age=3600
strict-transport-security: max-age=63072000; includeSubDomains
x-markdown-tokens: 725
x-original-tokens: 12345
content-signal: ai-train=yes, search=yes, ai-input=yes

---
title: Markdown for Agents · Cloudflare Agents docs
---

## What is Markdown for Agents

Markdown has quickly become the lingua franca for agents and AI systems
as a whole. The format’s explicit structure makes it ideal for AI processing,
ultimately resulting in better results while minimizing token waste.
...

Markdown for Agents は、変換後のレスポンスでもオリジンレスポンスのヘッダーを保持します。そのため、セキュリティやキャッシュに関わるヘッダーは変換後も残ります。対象には Strict-Transport-Security (HSTS)、Content-Security-Policy (CSP)、X-Frame-Options、Set-Cookie、CORS ヘッダー（例: Access-Control-Allow-Origin）、キャッシュヘッダー（Cache-Control、Expires、Age）が含まれます。

本文は変換後の Markdown に置き換わるため、次の変更が入ります。

• Content-Type は text/markdown; charset=utf-8 になります。
• Vary に Accept が含まれます（オリジンがすでに宣言している Vary 次元は保持されます）。キャッシュは Markdown と HTML を別バリアントとして保存します。
• Content-Length は Markdown レスポンスのサイズに合わせて再計算されます。
• 元の本文を説明するヘッダーは、変換後のレスポンスと一致しないため削除されます。対象は Content-Encoding、Content-Range、Transfer-Encoding、ETag、Last-Modified です。ETag と Last-Modified を外すのは、条件付きリクエスト（If-None-Match、If-Modified-Since）を変換後レスポンスでは満たせないためです。

Markdown for Agents は、次に説明するトークン数ヘッダーも追加します。

変換後のレスポンスには、トークン数ヘッダーが含まれます。x-markdown-tokens は Markdown ドキュメントの推定トークン数、x-original-tokens は変換前の元 HTML ドキュメントの推定トークン数です。コンテキストウィンドウのサイズ計算、Markdown 変換によるトークン削減の見積もり、チャンク分割方針の決定などに使えます。

Content Signals ↗ は、アクセス後のコンテンツの使い方について、希望を表明できる枠組みです。

オリジンがすでに content-signal ヘッダーを設定している場合、Markdown for Agents はその値を変換後レスポンスでも保持します。オリジンのポリシーが優先されます。オリジンで content-signal ヘッダーを設定すれば、独自の Content Signal ポリシーを定義できます。

オリジンレスポンスに content-signal ヘッダーがない場合、Markdown for Agents はデフォルトの Content-Signal: ai-train=yes, search=yes, ai-input=yes を追加します。コンテンツを AI Training、検索結果、AI Input（エージェント利用を含む）に使えることを示します。

Markdown for Agents は、サイトごとの解析ロジックなしで AI システムが扱えるよう、一貫した予測可能な構造の Markdown ドキュメントを返します。レスポンスは常に次のレイアウトです。

1. YAML frontmatter — ページの <meta> タグから抽出したメタデータです。対応するメタタグが 1 つ以上あるときだけ出力されます。
2. 本文の Markdown — ドキュメント本文から変換します。ヘッダー、フッター、ナビゲーション、スクリプト、スタイルなど、本文以外の要素は前処理で取り除きます。削除対象の一覧は、Workers AI Markdown Conversion のドキュメントの HTML 前処理 を参照してください。
3. JSON-LD — 構造化データを、ドキュメント末尾の json フェンス付きコードブロックとして保持します。元の HTML に JSON-LD があるときだけ出力されます。

元の HTML に対応する <meta> タグがある場合、Markdown for Agents はレスポンスの先頭に YAML frontmatter ブロックを付けます。ブロックのフィールドは次のとおりです。

値があるフィールドだけが出力されます。対応するメタタグがどれもなければ、frontmatter ブロック自体が省略されます。

title と description では、HTML 内の出現順に関係なく、標準の <meta name="..."> 形式が Open Graph の <meta property="og:..."> 形式より常に優先されます。Open Graph の値は、標準形式がないときのフォールバックです。

出力例:

---
title: My Page Title
description: A short summary of the page.
image: https://example.com/cover.png
---

# Page heading

...

JSON-LD ↗ は、検索エンジンや AI システムがページの意味内容を解釈するために使う構造化データ形式です。Markdown for Agents は、元の HTML にある <script type="application/ld+json"> ブロックを、変換後 Markdown の末尾に、1 つの json フェンス付きコードブロックとして追加します。

元の HTML に複数の JSON-LD スクリプトがある場合は、同じコードブロック内に連結し、それぞれを 1 行にします。

出力で保持される <script> は JSON-LD だけです。それ以外の <script> と <style> は HTML 前処理 で取り除きます。

出力例:

... main markdown content ...

```json
{
	"@context": "https://schema.org",
	"@type": "Article",
	"headline": "Article Title",
	"author": { "@type": "Person", "name": "Jane Doe" }
}
```

curl -X PATCH 'https://api.cloudflare.com/client/v4/zones/{zone_tag}/settings/content_converter' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer {api_token}" --data-raw '{"value": "on"}'

curl --request PUT \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_config_settings/entrypoint" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": [{
      "expression": "http.host eq \"docs.example.com\"",
      "action": "set_config",
      "action_parameters": {
        "content_converter": true
      },
      "description": "Enable Markdown for Agents for docs subdomain"
    }]
  }'

curl --request PATCH \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_metadata": {
      "content_converter": "enabled"
    }
  }'

curl --request PUT \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_config_settings/entrypoint" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": [{
      "expression": "lookup_json_string(cf.hostname.metadata, \"content_converter\") eq \"enabled\"",
      "action": "set_config",
      "action_parameters": {
        "content_converter": true
      },
      "description": "Enable content converter for opted-in custom hostnames"
    }]
  }'

Markdown for Agents は、Pro、Business、Enterprise プランと SSL for SaaS のお客様に、追加料金なしで提供されます。

この機能は Developer Documentation ↗ と Blog ↗ で有効にしています。AI クローラーとエージェントには、HTML ではなく Markdown でコンテンツを利用してもらう想定です。

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

• 変換対象は HTML のみです。ほかの種類のドキュメントは将来追加する可能性があります。
• オリジンレスポンスは 2 MB（2,097,152 バイト）を超えられません。

Cloudflare 外の任意ドキュメント変換が必要な AI システムを構築している場合や、コンテンツ元で Markdown for Agents が使えない場合は、アプリケーション向けに別の Markdown 変換手段があります。

• Workers AI の AI.toMarkdown() は、複数のドキュメント種類と要約に対応します。
• Browser Run の /markdown エンドポイントは、変換前に動的ページやアプリケーションを実ブラウザーで描画する必要がある場合に使えます。