Markdown cho AI agent: Accept: text/markdown là gì và có nên bật không?

Câu trả lời ngắn: Khi một AI agent gửi header Accept: text/markdown, website có thể trả về chính trang đó dưới dạng markdown thay vì HTML. Đây là content negotiation, một phần sẵn có của chuẩn HTTP. Cloudflare biến nó thành một nút bật từ tháng 2/2026, và Claude Code đã gửi header này. Trên sáu trang chúng tôi đo, bản markdown nhẹ hơn HTML 7 đến 99 lần. Nó không giúp lên hạng Google; nó giúp agent đọc trang của bạn rẻ và sạch hơn.

Markdown content negotiation là gì?

Mỗi request HTTP có header Accept liệt kê định dạng client muốn nhận. Trình duyệt gửi text/html. Một agent thích markdown gửi text/markdown, thường kèm text/html để dự phòng. Máy chủ đọc header này và chọn định dạng; cơ chế này có trong chuẩn HTTP (RFC 9110) từ lâu. Phản hồi markdown đúng chuẩn có hai header:

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

Xem thêm khái niệm tại Markdown content negotiation. Đây là một trong 9 check chính của Agent Readiness.

Vì sao AI agent muốn markdown?

Agent trả tiền theo token và có giới hạn ngữ cảnh. Một trang HTML mang theo menu, script, style và class CSS mà agent không cần. Cloudflare nêu ví dụ: tiêu đề ## About Us tốn khoảng 3 token, còn thẻ HTML tương ứng có class và id tốn 12 đến 15 token. Chúng tôi đo sáu trang ngày 19/10/2026, gửi một lượt dạng trình duyệt và một lượt dạng agent:

Trang	HTML (~token)	Markdown (~token)	Nhẹ hơn
vercel.com/docs	223.044	2.259	99×
docs.stripe.com/payments	110.265	1.289	86×
docs.claude.com (Claude Code overview)	139.316	4.129	34×
blog.cloudflare.com/markdown-for-agents	79.155	4.523	18×
developers.cloudflare.com (Markdown for Agents)	44.016	4.089	11×
citestat.com/en/blog/llms-txt-guide (sau khi sửa)	14.657	2.075	7×

Nguồn: CiteStat, scripts/growth/markdown-negotiation-check.ts. Token ước tính bằng số ký tự chia 4, một quy tắc thô, không phải bộ đếm token thật. Tỷ lệ phụ thuộc vào việc mỗi website đưa gì vào bản markdown; trang có nhiều menu và script thì giảm nhiều hơn. Không phản hồi nào chúng tôi nhận được có header x-markdown-tokens.

Lỗi của chính chúng tôi

Website CiteStat đã "hỗ trợ" markdown từ tháng 6: một middleware trả file llms.txt khi header Accept có text/markdown. Công cụ quét của chính chúng tôi chấm đạt, vì khi đó nó chỉ hỏi trang chủ (đã sửa ngày 21/10/2026). Khi kiểm tra từng URL, chúng tôi thấy hai lỗi:

• Agent xin bài blog /en/blog/llms-txt-guide nhận về llms.txt, tức bản tóm tắt cả website, không phải bài viết.
• Header có text/html làm dự phòng (ví dụ text/markdown, text/html, */*) bị bỏ qua, nên agent nhận HTML đầy đủ.

Bản sửa: trang chủ vẫn trả llms.txt (đó đúng là bản markdown của trang chủ), mỗi bài blog trả chính bài đó dạng markdown, các trang khác giữ HTML. Mọi phản hồi có Vary: Accept, và mỗi bài có thêm bản .md cùng header Link trỏ tới nó. Bài học: đừng chỉ hỏi "có trả markdown không", hãy hỏi "có trả đúng trang đó không".

Cách bật markdown negotiation

Cách 1: Cloudflare

Nếu website dùng Cloudflare gói Pro trở lên, bật Markdown for Agents trong AI Crawl Control. Cloudflare chuyển HTML sang markdown tại edge, giới hạn 6 MiB HTML mỗi trang, tự thêm Vary: Accept, bỏ ETag và Last-Modified trên bản markdown, và thêm header Content-Signal mặc định nếu máy chủ chưa đặt (tài liệu Cloudflare). Gói Free chưa có tính năng này.

Cách 2: tự làm trên máy chủ

1. Đọc header Accept. Chọn markdown khi text/markdown có trong danh sách và không bị xếp thấp hơn text/html (so q-value).
2. Tạo markdown từ cùng nội dung của trang: tiêu đề, nội dung chính, bảng, liên kết tuyệt đối. Bỏ menu, footer, script.
3. Trả Content-Type: text/markdown; charset=utf-8 và Vary: Accept. Đặt Vary: Accept cả trên bản HTML.
4. Tùy chọn: bản .md ở URL trang thêm đuôi .md, khai báo bằng Link: </bai-viet.md>; rel="alternate"; type="text/markdown", và liệt kê trong llms.txt.

Kiểm tra bằng hai lệnh: curl -sI -H 'Accept: text/markdown' https://ten-mien/trang phải cho Content-Type markdown và Vary: Accept; curl -s -H 'Accept: text/markdown' https://ten-mien/trang | head phải bắt đầu bằng tiêu đề của chính trang đó.

Năm lỗi thường gặp

1. Trả bản tóm tắt website cho mọi URL (lỗi của chúng tôi). Agent hỏi một trang, nhận một trang khác.
2. Thiếu Vary: Accept. CDN có thể lưu bản markdown rồi trả cho người dùng trình duyệt.
3. So sánh chuỗi Accept quá cứng. Chỉ nhận đúng text/markdown sẽ bỏ sót agent gửi kèm text/html.
4. Markdown thiếu nội dung chính vì nội dung đó do JavaScript tạo. Bộ chuyển đổi chỉ thấy HTML máy chủ gửi, giống AI crawler không chạy JavaScript.
5. Coi đây là tín hiệu xếp hạng. Hướng dẫn AI features của Google nói không cần file hay markup đặc biệt cho AI Overviews.

Nên làm gì trước?

Markdown negotiation là bước sau cùng, không phải bước đầu. Trước nó: HTML hiển thị phía máy chủ, robots.txt không chặn AI crawler bạn muốn, và tiêu đề, mô tả, nội dung chính đều có trong HTML đầu tiên. Website bán hàng nhỏ có thể dừng ở đó. Trang tài liệu, API hay bảng giá, nơi trợ lý lập trình và agent hay đọc, thì đáng bật.

CiteStat kiểm tra thế nào?

Khi bạn quét một URL, CiteStat gửi Accept: text/markdown, text/html, */* tới chính URL đó và chỉ chấm đạt khi phản hồi là markdown, tiêu đề markdown là phần mở đầu của H1 hoặc title của trang (không phải bản tóm tắt site), và có Vary: Accept. Kết quả nằm trong thẻ Agent Readiness cùng 8 check khác như Link header, MCP Server Card và API Catalog. Để kiểm tra trang khác, dùng hai lệnh curl ở trên.

Gói miễn phí có 10 lượt quét mỗi ngày. Nếu bạn quản lý nhiều website hoặc cần báo cáo AI render đầy đủ, xem bảng giá: gói Pro 500.000₫/tháng (chưa VAT) cho 100 lượt quét mỗi ngày.

FAQ

Accept: text/markdown có giúp lên hạng Google không?

Không. Google đọc HTML bình thường, và hướng dẫn AI features của Google nói không cần file hay markup đặc biệt nào để xuất hiện trong AI Overviews hay AI Mode. Markdown negotiation giúp AI agent và trợ lý lập trình đọc trang của bạn rẻ hơn, không phải giúp xếp hạng.

Agent nào đang gửi Accept: text/markdown?

Cloudflare nêu Claude Code và OpenCode trong bài ra mắt Markdown for Agents (12/2/2026). Các agent khác có thể gửi header này mà không công bố; cách chắc chắn nhất là xem log máy chủ của bạn.

Trả nội dung khác nhau cho bot và người dùng có bị coi là cloaking không?

Không, nếu markdown là cùng nội dung với trang HTML. Cloaking là cho bot xem nội dung khác người dùng. Ở đây chỉ định dạng thay đổi, và lựa chọn dựa vào header Accept do client gửi, không dựa vào user agent.

Có cần header Vary: Accept không?

Có. Vary: Accept báo cho CDN và bộ nhớ đệm rằng cùng một URL có hai bản theo header Accept. Thiếu nó, bộ nhớ đệm có thể trả bản markdown cho trình duyệt hoặc trả HTML cho agent.

Nên dùng markdown negotiation hay bản .md riêng?

Có thể làm cả hai. Negotiation phục vụ agent tự xin markdown ở URL gốc. Bản .md (URL trang thêm .md) là thứ đặc tả llms.txt gợi ý, và header Link rel="alternate" type="text/markdown" trỏ tới nó giúp agent tìm ra.