Markdown voor AI-agents: Accept text/markdown, Content-Signal en Link Headers uitgelegd

Kort antwoord: Markdown voor AI-agents betekent dat je server hetzelfde adres met gewone Markdown beantwoordt in plaats van met HTML, wanneer de aanvrager daarom vraagt met de request-header Accept: text/markdown. Browsers blijven HTML krijgen. Daarvoor zijn een paar regels servercode nodig, of een CDN-functie die je aanzet, en agents krijgen schone tekst zonder menu’s en scripts. Een voordeel voor rankings of AI-vermeldingen is niet aangetoond. Zie het als een goedkope extra bovenop leesbare HTML, een goede robots.txt en een sitemap, nooit als vervanging daarvan.

Waarom houden AI-agents van Markdown?

Een webpagina is gebouwd voor browsers. Rond de tekst die je wilt lezen staan navigatie, een cookiebanner, scripts, stijlklassen en voetteksten. Het menselijk oog slaat dat allemaal over. Een programma dat de pagina aan een taalmodel moet doorgeven, kan dat niet gratis overslaan: het model heeft een beperkt contextvenster en elk extra element neemt er een deel van in beslag.

Markdown houdt over wat voor het lezen telt: koppen, alinea’s, lijsten, tabellen, links. Daarom liggen agents en vergelijkbare tools voor de hand als afnemers, en daarom is ook het voorstel voor llms.txt in Markdown geschreven. Over dat bestand schreven we in Wat is llms.txt?.

Cloudflare maakt het verschil in omvang zichtbaar. In de aankondiging van Markdown for Agents bevat het voorbeeldantwoord een header x-markdown-tokens met een geschat aantal tokens (725 in het voorbeeld), zodat een aanvrager kan inschatten hoeveel context een pagina kost.

Wat dit niet vertelt, is of de grote AI-zoeksystemen om Markdown vragen. De aankondiging van Cloudflare toont Radar-gegevens over Markdown-antwoorden aan OAI-SearchBot. Dat bewijst dat zulke antwoorden voorkomen, niet dat de crawler erom vraagt; OpenAI documenteert dat niet. Dus beweren we het niet. Wel gedocumenteerd is dat sommige agents er al om vragen, zoals de volgende secties laten zien.

Hoe content negotiation werkt: Accept, Vary en Content-Type

Content negotiation (in het Nederlands inhoudsonderhandeling) is een oud onderdeel van HTTP. Eén adres kan meerdere weergaven hebben, en de aanvrager zegt welke hij verkiest. Drie headers dragen het hele mechanisme:

Een browser noemt eerst text/html en voegt als terugvaloptie de wildcard */* toe. Een agent die Markdown wil, noemt het uitdrukkelijk, bijvoorbeeld Accept: text/markdown of Accept: text/markdown, text/html;q=0.8. Cloudflare schrijft dat gangbare programmeeragents zoals Claude Code en OpenCode zulke Accept-headers al versturen.

De regel die iedereen beschermt, is eenvoudig: antwoord alleen met Markdown als text/markdown uitdrukkelijk wordt genoemd en niet lager wordt gewaardeerd dan text/html. De wildcard */* mag nooit meetellen. Anders zouden browsers, linkcheckers en previewbots van sociale netwerken, die allemaal “alles” accepteren, plotseling Markdown krijgen.

Markdown voor AI-agents met Cloudflare

Op 12 februari 2026 kondigde Cloudflare Markdown for Agents aan. Is de functie voor jouw zone ingeschakeld (ze is als bèta gratis beschikbaar in de abonnementen Pro, Business en Enterprise), dan krijgt een verzoek met Accept: text/markdown je HTML direct omgezet naar Markdown terug. Je origin-server blijft ongewijzigd.

Het voorbeeldantwoord uit de aankondiging laat zien welke headers je kunt verwachten:

content-type: text/markdown; charset=utf-8
vary: accept
x-markdown-tokens: 725
content-signal: ai-train=yes, search=yes, ai-input=yes

Dat is de snelste weg als je website toch al achter Cloudflare draait in een van die abonnementen en het omgezette resultaat er goed uitziet. Controleer het met curl (zie “Zo test je het met curl”) voordat je erop vertrouwt. Wil je zelf bepalen wat de Markdown-versie zegt, of draait je site elders, bouw het dan zelf.

Zelf bouwen: een kort Node-voorbeeld

De volgende schets bevat de regels van hierboven: Markdown alleen bij een uitdrukkelijk verzoek, Vary: Accept op beide versies, een vast adres /index.md voor aanvragers die niet onderhandelen, en een canonical-link in de header van het Markdown-antwoord. Het is een minimaal voorbeeld, geen productiecode.

import http from 'node:http';
import { readFileSync } from 'node:fs';

function wantsMarkdown(accept = '') {
  const weight = new Map();
  for (const part of accept.toLowerCase().split(',')) {
    const [range, ...params] = part.trim().split(';');
    const q = params.find((p) => p.trim().startsWith('q='));
    weight.set(range.trim(), q ? Number(q.trim().slice(2)) : 1);
  }
  const md = weight.get('text/markdown') ?? 0;
  const html = weight.get('text/html') ?? weight.get('text/*') ?? weight.get('*/*') ?? 0;
  return md > 0 && md >= html; // de wildcard alleen kiest nooit Markdown
}

http.createServer((req, res) => {
  if (req.url === '/index.md' || (req.url === '/' && wantsMarkdown(req.headers.accept))) {
    res.writeHead(200, {
      'Content-Type': 'text/markdown; charset=utf-8',
      'Vary': 'Accept',
      'Link': '<https://example.com/>; rel="canonical"',
    });
    return res.end(readFileSync('index.md'));
  }
  if (req.url === '/') {
    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Vary': 'Accept' });
    return res.end(readFileSync('index.html'));
  }
  res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); // elk ander adres antwoordt 404
  res.end('Not found');
}).listen(3000);

Drie details verdienen een tweede blik:

• Vary op beide versies. Ook het HTML-antwoord heeft Vary: Accept nodig. Anders kan een gedeelde cache de HTML opslaan en uitleveren aan een agent die om Markdown vroeg, of andersom.
• Het vaste adres. /index.md geeft altijd Markdown, wat de aanvrager ook stuurt. Agents en mensen kunnen ernaar linken, en het werkt waar je geen headers kunt zetten. Onze eigen seogrinder.com/index.md doet het zo.
• De canonical-header. De Markdown-versie is een tweede weergave van dezelfde pagina. Google documenteert dat rel="canonical" bij bestanden die geen HTML zijn als HTTP-header mag worden verstuurd. Het is een sterk signaal dat de Markdown-versie bij de pagina hoort, maar geen garantie (Google).

Schrijf het Markdown-bestand met de hand of genereer het uit dezelfde bron als de HTML. In beide gevallen moet het hetzelfde zeggen als de pagina, alleen zonder het kader eromheen.

Link-headers: agents wijzen op de beschrijving van je site

De responseheader Link is vastgelegd in RFC 8288. Hij noemt een verwant adres en het soort relatie, bijvoorbeeld Link: </llms.txt>; rel="describedby". De relatie describedby is geregistreerd en de betekenis past: de gelinkte bron beschrijft deze bron. Een aanvrager die responseheaders leest, weet zo waar de beschrijving van je website staat nog voordat hij de body leest.

seogrinder.com stuurt deze header op de startpagina en wijst daarmee naar de eigen llms.txt. Bij het Markdown-antwoord draagt dezelfde Link-header bovendien de relatie canonical van hierboven, gescheiden door een komma.

Of een agent deze links vandaag volgt, is niet aangetoond. De kosten zijn één regel in de serverconfiguratie.

De Content-Signal-regel

In september 2025 voerde Cloudflare voor de robots.txt een regel in die zegt wat een crawler met je inhoud mag doen nadat hij die heeft opgehaald:

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

search staat voor indexeren en snippets, ai-input voor het rechtstreeks gebruiken van de inhoud in AI-antwoorden en ai-train voor het trainen of bijsturen van een model. Het formaat staat beschreven in de aankondiging van Cloudflare en op contentsignals.org. Het is een verklaring, geen barrière: niemand is verplicht haar na te leven. Cloudflare zegt dat Content Signals voorkeuren uitdrukken, geen technische tegenmaatregelen zijn en dat sommige bedrijven ze gewoon zouden kunnen negeren. Zoals hierboven getoond, draagt ook het Markdown-voorbeeld van Cloudflare een responseheader content-signal.

De regel hoort in je robots.txt, bij alle andere regels voor AI-bots. De details, ook de veelgemaakte fout met aparte groepen per bot, vind je in robots.txt voor AI-crawlers. De robots.txt van seogrinder.com gebruikt één gezamenlijke groep voor alle crawlers en negen AI-kenmerken, met Content-Signal: search=yes, ai-input=yes, ai-train=yes.

Zo test je het met curl

Test met hetzelfde gereedschap dat ook een agent zou gebruiken. De optie -I toont alleen de headers:

curl -sI -H "Accept: text/markdown" https://example.com/

Let in het antwoord op vier dingen: status 200, content-type: text/markdown, een vary die Accept bevat en een link-header met het canonical-adres. Zo ziet het resultaat voor seogrinder.com eruit, ingekort tot de relevante regels:

HTTP/2 200
content-type: text/markdown; charset=utf-8
vary: Accept
link: </llms.txt>; rel="describedby"; type="text/plain", <https://seogrinder.com/>; rel="canonical"

Doe daarna de tegenproeven. Elk van deze moet text/html opleveren:

curl -sI -H "Accept: text/html" https://example.com/
curl -sI -H "Accept: */*" https://example.com/
curl -sI https://example.com/

Stuur ten slotte -H "Accept: text/markdown, text/html;q=0.8". Markdown hoort te winnen, omdat het hoger is gewaardeerd.

Zo controleert SEOgrinder het

Open na een scan in SEOgrinder het tabblad AI-gereedheid. Onder “Controles voor AI-agents” staan zeven regels. Drie daarvan gaan over dit artikel, en alle drie staan in de groep “Extra’s”:

• Tekst in plaats van HTML leveren (Markdown Negotiation): voldaan als een verzoek met Accept: text/markdown Markdown terugkrijgt.
• Agents naar je data leiden (Link Headers): zoekt nuttige relaties in de responseheader.
• Gebruik van de inhoud verklaren (Content Signals): zoekt een volledige Content-Signal-regel die ai-train, search en ai-input dekt.

Openstaande punten tonen de knop Agent-prompt kopiëren direct in de regel; voldane punten tonen hem pas als je de regel uitklapt, samen met de gevonden tekst. Bij een openstaand punt beschrijft de prompt wat je moet maken, toont hij met curl de huidige toestand en noemt hij een commando om het resultaat te controleren. Bij een voldaan punt vraagt hij je programmeerassistent het bestaande te controleren, alleen te wijzigen wat nodig is en jou te vragen voordat hij een regel verwijdert die hij niet begrijpt. Beslissingen zoals AI-crawlers toestaan of blokkeren blijven bij jou, en sommige prompts voor openstaande punten stellen voorbeeldwaarden voor. Beslis dus eerst en lees de prompt voordat je hem in Claude Code, Cursor, GitHub Copilot of ChatGPT plakt. Klik daarna op Opnieuw controleren. Rapporten blijven tot 24 uur in de cache, en Opnieuw controleren forceert een nieuwe controle (een paar keer per uur).

SEOgrinder is eerlijk over de groep “Extra’s”: dit zijn suggesties van afzonderlijke aanbieders en een effect op Google is niet aangetoond. De tool meet ook niet of ChatGPT, Gemini of Perplexity je merk werkelijk noemen. Hij controleert de technische basis: kunnen machines je pagina bereiken en lezen?

Is de moeite het waard?

Dat hangt af van wat je website biedt. Documentatie, naslagpagina’s, lange handleidingen en kennisbanken zijn het soort inhoud dat agents ophalen om een concrete vraag te beantwoorden, en daar is een nette Markdown-versie nuttig. Voor een kleine webwinkel of een lokaal bedrijf met vijf pagina’s besteed je je tijd beter aan de basis: tekst die ook zonder JavaScript in de HTML staat, een robots.txt die de zoekbots binnenlaat en een sitemap.

Voor de eigen AI-functies van Google zegt Google dat er geen extra eisen zijn om in AI-overzichten of AI Mode te verschijnen en dat er ook geen andere speciale optimalisaties nodig zijn; de details staan in de documentatie van Google. Een Markdown-versie is daar dus geen vereiste. Andere assistenten kunnen zich anders gedragen, maar niemand kan beloven dat een AI-assistent jouw pagina noemt.

Veelgemaakte fouten

• Geen Vary-header. Zonder Vary: Accept kan een cache of CDN de volgende bezoeker de verkeerde versie geven.
• Een voorgeschakelde cache die de header negeert. Test via het openbare adres, niet alleen tegen je origin-server.
• Markdown voor browsers. Behandelt je controle de wildcard */* als verzoek om Markdown, dan zien bezoekers ruwe tekst. Test met een gewone browser.
• Geen canonical-link. De Markdown-versie kan dan als aparte pagina worden behandeld. Wij kozen voor de canonical-header in plaats van noindex, omdat de onderhandelde versie onder hetzelfde adres staat als de pagina.
• Een Markdown-versie die iets anders zegt. Houd de inhoud gelijk aan de HTML-pagina, alleen zonder het kader. We hebben geen bron over hoe zoekmachines verschillen tussen beide behandelen, dus houd ze identiek.
• Een verouderd bestand. Een met de hand geschreven index.md met het aanbod van vorig jaar leidt agents op een dwaalspoor. Genereer het uit de bron van de pagina, of zet het op je checklist.
• Een lege HTML-pagina. Heeft de HTML zelf geen tekst totdat JavaScript is gelopen, dan lost Markdown voor agents het probleem bij de andere aanvragers niet op, zoals bij previews op sociale media. SEOgrinder meldt pagina’s die pas in de browser worden opgebouwd.

Veelgestelde vragen

Is Markdown voor AI-agents een rankingfactor?

Daar is geen bewijs voor. Zie het als een leveringsformaat voor machines, niet als rankinghefboom.

Vragen ChatGPT, Claude of Perplexity om Markdown?

Cloudflare schrijft dat programmeeragents zoals Claude Code en OpenCode Accept: text/markdown al versturen. Voor de zoekcrawlers van de grote aanbieders bestaat geen documentatie dat ze erom vragen; de Radar-gegevens van Cloudflare tonen Markdown-antwoorden aan OAI-SearchBot, en dat is geen bewijs voor een request-header. Het is dus niet aangetoond.

Heb ik Cloudflare nodig?

Nee. Cloudflare biedt de omzetting aan als functie (als bèta, in de abonnementen Pro, Business en Enterprise). Het Node-voorbeeld hierboven laat zien dat een paar regels servercode volstaan, en dezelfde regels zijn in elke server of elk framework te bouwen.

Moet ik content negotiation gebruiken of een apart .md-adres?

Je kunt beide doen. Een vast adres als /index.md is gemakkelijk te linken en te testen. Met onderhandeling houd je één adres voor beide doelgroepen. seogrinder.com biedt beide aan voor de startpagina.

Zien gewone bezoekers ooit de Markdown-versie?

Niet als je de regel over de wildcard volgt: Markdown gaat alleen de deur uit als text/markdown uitdrukkelijk wordt genoemd en niet lager is gewaardeerd dan text/html.

Je volgende stap

Start de gratis scan in SEOgrinder en open het tabblad AI-gereedheid. Bekijk de drie extra regels voor Markdown, Link Headers en Content Signals en beslis of jouw website bij de sites hoort die agents lezen. Zo ja, kopieer dan de agent-prompt, laat je assistent de wijziging doen, controleer het resultaat met curl en scan opnieuw.