Markdown para agentes de IA sem quebrar cache e SEO
Markdown para agentes de IA é a mesma página servida em text/markdown, sem menu, rodapé nem scripts. A entrega pode ser feita na mesma URL, quando o pedido traz o cabeçalho Accept com text/markdown, ou em um endereço próprio, como o sufixo /md/. As duas vias precisam de canonical apontando para o HTML e de cuidado com o cache, porque a CDN da Cloudflare ignora o Vary por padrão. Neste site uso as duas vias, com canonical por cabeçalho HTTP e a resposta em Markdown fora do cache.
- No post de lançamento do Markdown for Agents, a Cloudflare mediu 16.180 tokens na versão HTML e 3.150 na versão Markdown, uma redução de 80%;
- Segundo a Cloudflare, em fevereiro de 2026, Claude Code e OpenCode já enviavam o cabeçalho Accept com text/markdown;
- A CDN da Cloudflare ignora o Vary por padrão e só o respeita quando ele é configurado nas Cache Rules, recurso listado para todos os planos;
- O Markdown for Agents da Cloudflare converte HTML na borda apenas nos planos Pro, Business e Enterprise, com limite de 2 MB por resposta de origem;
- O Google aceita rel="canonical" em cabeçalho HTTP Link, inclusive para documentos que não são HTML.
Duas portas para a mesma página
A versão Markdown de uma página pode ser entregue por negociação de conteúdo ou por um endereço próprio, e cada via atende um tipo de cliente. Na negociação, o endereço é o mesmo: o cliente manda o cabeçalho Accept com text/markdown e o servidor responde com Content-Type text/markdown. No endereço próprio, a versão mora em uma URL paralela, como /pagina/md/, e serve a qualquer agente que siga um link, mesmo sem negociar formato.
O ganho de tamanho é real. No post de lançamento do Markdown for Agents, em fevereiro de 2026, a Cloudflare mediu o próprio texto em 16.180 tokens na versão HTML e 3.150 na versão Markdown, uma redução de 80%. No mesmo post, a empresa afirma que Claude Code e OpenCode já mandavam o cabeçalho Accept pedindo Markdown. A lista não inclui os robôs de rastreamento das grandes empresas de IA, e é por isso que eu não dependo só da negociação.
No post de lançamento do Markdown for Agents, em fevereiro de 2026, a Cloudflare mediu o próprio texto em 16.180 tokens na versão HTML e 3.150 na versão Markdown, uma redução de 80%.
Lucas Ferraz, especialista em SEO
Uma definição curta de quem faz esse pedido está no verbete de agente de IA da agência.
Como anunciar a versão Markdown?
O HTML anuncia a alternativa com um link rel="alternate" do tipo text/markdown no head, e o llms.txt pode repetir a regra de formação das URLs. O anúncio no head fica assim:
<link rel="alternate" type="text/markdown" href="https://exemplo.com/pagina/md/" title="Versão em Markdown">O Google avisa que anotações rel="canonical" com atributo type não entram na canonicalização. Canonical e alternate precisam ser dois elementos separados, cada um com a própria função.
Canonical por cabeçalho ou noindex
O Google aceita o canonical em um cabeçalho HTTP Link, método pensado para documentos que não são HTML e suportado nos resultados da busca na web. A resposta em Markdown pode então apontar para a página HTML sem mexer no corpo:
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept
Link: <https://exemplo.com/pagina/>; rel="canonical"A alternativa comum é mandar X-Robots-Tag com noindex na versão Markdown. As duas saídas evitam a disputa entre versões, com efeitos diferentes. O noindex tira o arquivo do índice e não consolida sinal nenhum. O canonical sugere ao Google que links e sinais da versão paralela contem para a URL principal. O próprio Google desaconselha usar noindex para escolher a canônica dentro do mesmo site, e por isso prefiro o cabeçalho Link.
Vary Accept e o cache que mistura formatos
Quando HTML e Markdown dividem a mesma URL, o cache precisa saber que a resposta depende do cabeçalho Accept. O cabeçalho Vary: Accept, definido na RFC 9110, avisa isso a qualquer cache intermediário. O problema está em quem ignora o aviso.
A documentação de cache da Cloudflare diz que, por padrão, a CDN desconsidera os valores de Vary nas decisões de cache. O Vary passa a valer quando é configurado nas Cache Rules, recurso que a página de agosto de 2026 lista como disponível nos planos Free, Pro, Business e Enterprise, e em casos específicos como Accept-Encoding e variantes de imagem. Sem essa configuração, a primeira versão guardada vale para todos: um agente pode receber HTML ou, pior, uma pessoa pode receber Markdown.
| Cenário na Cloudflare | Risco | Saída |
|---|---|---|
| Vary: Accept sem configuração nas Cache Rules | Versões misturadas no cache | Regra de bypass para pedidos de Markdown |
| Vary configurado nas Cache Rules com normalização | Baixo, com o Accept normalizado | Testar as duas versões depois de cada purge |
| Markdown for Agents ligado | Conversão na borda, só em plano pago | Conferir o limite de 2 MB por resposta |
O Markdown for Agents resolve a conversão e já devolve Vary: accept, mas a documentação o restringe aos planos Pro, Business e Enterprise e remove da resposta convertida os cabeçalhos ETag e Last-Modified.
Como este site serve Markdown?
Neste site, toda página tem versão Markdown no sufixo /md/ e na própria URL quando o pedido traz Accept com text/markdown. A resposta sai com Content-Type text/markdown, Cache-Control no-store, Vary: Accept e o canonical em cabeçalho Link apontando para a versão HTML. A página HTML também declara Vary: Accept e anuncia a alternativa no head. Na Cloudflare, uma regra de bypass para Accept contendo text/markdown ou URL terminada em /md/ vem antes da regra de cache. A regra não depende da configuração de Vary, e por isso a mantenho mesmo com o recurso disponível no plano gratuito.
O teste cabe em duas linhas:
curl -sI -H "Accept: text/markdown" https://lucasferraz.com/politica-editorial/
curl -sI https://lucasferraz.com/politica-editorial/md/As duas respostas devem trazer content-type text/markdown e o cabeçalho Link com o canonical. A mesma lógica vale para o llms.txt, que aqui funciona como índice curado das versões em Markdown. No benchmark de agências de GEO, só 1 das 19 agências brasileiras mantinha uma via dedicada para agentes lerem o site de forma estruturada.
O que medir depois de publicar?
A versão Markdown ainda não tem estudo público que a ligue a mais citações por IA. O que dá para medir é uso: filtrar no log os pedidos com Accept contendo text/markdown e os pedidos a /md/, separar por user agent e comparar com os pedidos da versão HTML feitos pelos mesmos robôs. A separação por função, entre treino, índice e visita a pedido do usuário, segue o método descrito em como identificar crawlers de IA no log do servidor. Se depois de alguns meses nenhum agente pedir Markdown, o custo terá sido pequeno e a resposta, útil.
O que a IA desdobra desta pergunta?
Quando alguém faz esta busca em uma IA, o sistema abre subperguntas antes de responder. Estas são as que apareceram na medição, e onde cada uma é respondida.
Perguntas frequentes
O risco existe se a versão Markdown for indexada como página própria. O Google aceita o canonical em cabeçalho HTTP Link para documentos que não são HTML, e a resposta em Markdown pode apontar para a URL em HTML. A outra saída é o X-Robots-Tag com noindex, que tira o arquivo do índice sem consolidar sinais.
A Cloudflare citou Claude Code e OpenCode, em fevereiro de 2026, como agentes que já enviam Accept com text/markdown. A lista não inclui os robôs de rastreamento das grandes empresas de IA, e por isso mantenho também o sufixo /md/ e o link alternate no head, que funcionam para quem não negocia formato.
Por padrão, não. A documentação de cache da Cloudflare diz que a CDN desconsidera o Vary nas decisões de cache, exceto quando ele é configurado nas Cache Rules, recurso listado para todos os planos, e em casos como o Accept-Encoding. Sem essa configuração, uma regra de bypass para pedidos de Markdown evita que HTML e Markdown se misturem.
Fontes citadas
Versão em markdown para agentes de IA: https://lucasferraz.com/blog/markdown-para-agentes-de-ia/md/
Leia também
Comércio agêntico (agentic commerce) além do checkout
Comércio agêntico pelos protocolos UCP, ACP e AP2, o que o site expõe ao agente e onde fica o serviço vendido por orçamento, com fontes de 2026.
knowsAbout ligado ao glossário e ao Wikidata
Como ligar o knowsAbout ao verbete do glossário pelo @id e ao Wikidata pelo sameAs, com o antes e depois de um grafo real e os erros comuns.
Auditoria de GEO com critério de medição por item
Checklist técnico de auditoria de GEO com critério de aprovação por item, de robôs e render a llms.txt, schema, velocidade e WordPress.