Markdown per agenti AI: Accept text/markdown, Content-Signal e Link header spiegati

Di SEOgrinder · Pubblicato il 4 novembre 2026 · 11 min di lettura

Risposta breve: Markdown per agenti AI significa che il tuo server risponde allo stesso indirizzo con Markdown puro invece che con HTML, quando il client lo chiede con l'header di richiesta Accept: text/markdown. I browser continuano a ricevere HTML. Bastano poche righe di codice sul server o una funzione di una CDN da attivare, e gli agenti ottengono testo pulito, senza menu e script. Un vantaggio per il ranking o per le citazioni delle AI non è dimostrato: consideralo un extra a basso costo che si aggiunge a un HTML leggibile, a un buon robots.txt e a una sitemap, mai un loro sostituto.

Perché gli agenti AI preferiscono il Markdown?

Una pagina web è costruita per i browser. Attorno al testo che vuoi leggere ci sono navigazione, banner dei cookie, script, classi di stile e piè di pagina. L'occhio di una persona salta tutto questo. Un programma che deve passare la pagina a un modello linguistico non può saltarlo gratis: il modello ha una finestra di contesto limitata, e ogni elemento in più ne consuma una parte.

Il Markdown conserva ciò che conta per la lettura: titoli, paragrafi, elenchi, tabelle, link. Per questo agenti e strumenti simili sono candidati naturali a chiederlo, e per lo stesso motivo anche la proposta llms.txt è scritta in Markdown. Di quel file abbiamo parlato in llms.txt: cos'è, come crearlo e se serve davvero.

Cloudflare rende visibile la differenza di dimensioni. Nell'annuncio di Markdown for Agents la risposta di esempio contiene un header x-markdown-tokens con una stima del numero di token (725 nell'esempio), così un client può valutare quanto contesto occuperà una pagina.

Ciò che questo non dice è se i grandi sistemi di ricerca AI chiedano Markdown. L'annuncio di Cloudflare mostra dati di Radar su risposte Markdown a OAI-SearchBot. Questo dimostra che tali risposte avvengono, non che il crawler le richieda; OpenAI non lo documenta. Quindi non lo affermiamo. È documentato invece che alcuni agenti lo chiedono già, come mostrano le prossime sezioni.

Come funziona la negoziazione del contenuto: Accept, Vary e Content-Type

La negoziazione del contenuto (content negotiation) è una parte antica di HTTP. Un indirizzo può avere più rappresentazioni, e il client indica quale preferisce. Tre header reggono l'intero meccanismo:

Header	Inviato da	Significato
`Accept`	Client, nella richiesta	Quali tipi di contenuto vuole, con pesi facoltativi (`q=0.8`)
`Content-Type`	Server, nella risposta	Che cosa il server ha davvero inviato, qui `text/markdown; charset=utf-8`
`Vary: Accept`	Server, nella risposta	La risposta dipende dall'header `Accept`, quindi le cache non devono mescolare le versioni

Un browser indica prima text/html e aggiunge come ripiego il carattere jolly */*. Un agente che vuole Markdown lo nomina esplicitamente, per esempio Accept: text/markdown oppure Accept: text/markdown, text/html;q=0.8. Cloudflare scrive che agenti di coding diffusi come Claude Code e OpenCode inviano già header Accept di questo tipo.

La regola che protegge tutti è semplice: rispondi con Markdown solo se text/markdown è nominato esplicitamente e non ha un peso inferiore a text/html. Il carattere jolly */* non deve mai contare. Altrimenti un browser, un controllo dei link o un bot per le anteprime social, che accettano tutti «qualsiasi cosa», riceverebbero Markdown.

Markdown per agenti AI con Cloudflare

Il 12 febbraio 2026 Cloudflare ha annunciato Markdown for Agents. Se la funzione è attiva per la tua zona (è in beta, senza costi aggiuntivi, nei piani Pro, Business ed Enterprise), una richiesta con Accept: text/markdown riceve il tuo HTML convertito in Markdown al volo. Il tuo server di origine non cambia.

La risposta di esempio dell'annuncio mostra gli header da aspettarsi:

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

È la strada più rapida se il tuo sito passa già da Cloudflare in uno di quei piani e il risultato convertito ti convince. Verifica il risultato con curl (vedi «Come provarlo con curl») prima di farci affidamento. Se vuoi controllare fino in fondo che cosa dice la versione Markdown, o se usi un'altra infrastruttura, costruiscila tu.

Costruirlo da sé: un breve esempio in Node

Lo schizzo qui sotto contiene le regole appena viste: Markdown solo su richiesta esplicita, Vary: Accept su entrambe le versioni, un indirizzo fisso /index.md per i client che non negoziano e un link canonical nell'header della risposta Markdown. È un esempio minimo, non codice di produzione.

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; // il carattere jolly da solo non sceglie mai 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' }); // ogni altro indirizzo risponde 404
  res.end('Not found');
}).listen(3000);

Tre dettagli meritano un secondo sguardo:

Vary su entrambe le versioni. Anche la risposta HTML ha bisogno di Vary: Accept. Altrimenti una cache condivisa può memorizzare l'HTML e consegnarlo a un agente che voleva Markdown, o viceversa.
L'indirizzo fisso. /index.md restituisce sempre Markdown, qualunque cosa invii il client. Agenti e persone possono linkarlo, e funziona dove non si possono impostare gli header. Il nostro seogrinder.com/index.md fa così.
L'header canonical. La versione Markdown è una seconda rappresentazione della stessa pagina. Google documenta che rel="canonical" può essere inviato come header HTTP per i file che non sono HTML. È un segnale forte che la versione Markdown appartiene alla pagina, non una garanzia (Google).

Scrivi il file Markdown a mano oppure generalo dalla stessa fonte dell'HTML. In ogni caso deve dire la stessa cosa della pagina, solo senza la cornice.

Link header: indicare agli agenti la descrizione del sito

L'header di risposta Link è definito nell'RFC 8288. Indica un indirizzo collegato e il tipo di relazione, per esempio Link: </llms.txt>; rel="describedby". La relazione describedby è registrata e il suo significato calza: la risorsa collegata descrive questa. Un client che legge gli header di risposta scopre così dove si trova la descrizione del tuo sito, prima ancora di leggere il corpo della risposta.

seogrinder.com invia questo header sulla pagina iniziale e rimanda al proprio llms.txt. Nella risposta Markdown lo stesso header Link porta in più la relazione canonical vista sopra, separata da una virgola.

Che oggi un agente qualsiasi segua questi link non è dimostrato. Il costo è una riga nella configurazione del server.

La riga Content-Signal

A settembre 2025 Cloudflare ha introdotto per il robots.txt una riga che dice che cosa un crawler può fare con i tuoi contenuti dopo averli richiesti:

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

search riguarda indicizzazione e snippet, ai-input l'uso diretto dei contenuti nelle risposte delle AI e ai-train l'addestramento o il fine-tuning di un modello. Il formato è descritto nell'annuncio di Cloudflare e su contentsignals.org. È una dichiarazione, non una barriera: nessuno è obbligato a rispettarla. Cloudflare afferma che i content signal esprimono preferenze, che non sono contromisure tecniche e che alcune aziende potrebbero semplicemente ignorarli. Come visto sopra, anche l'esempio Markdown di Cloudflare porta un header di risposta content-signal.

La riga va nel tuo robots.txt, insieme a tutte le altre regole per i bot AI. I dettagli, compreso l'errore frequente dei gruppi separati per ogni bot, sono in robots.txt per crawler AI. Il robots.txt di seogrinder.com usa un gruppo comune per tutti i crawler e nove identificatori AI, con Content-Signal: search=yes, ai-input=yes, ai-train=yes.

Come provarlo con curl

Verifica con lo stesso strumento che userebbe un agente. L'opzione -I mostra solo gli header:

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

Nella risposta cerca quattro cose: stato 200, content-type: text/markdown, un vary che contenga Accept e un header link con l'indirizzo canonical. Questo è il risultato per seogrinder.com, ridotto alle righe rilevanti:

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"

Poi fai le prove contrarie. Ognuna deve restituire text/html:

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

Infine invia -H "Accept: text/markdown, text/html;q=0.8". Deve vincere il Markdown, perché ha un peso più alto.

Come lo controlla SEOgrinder

Dopo una scansione apri la scheda Preparazione all'IA in SEOgrinder. Sotto «Controlli per agenti IA» trovi sette righe. Tre riguardano questo articolo e stanno tutte nel gruppo «Extra»:

Servire testo invece di HTML (Markdown Negotiation): soddisfatto quando una richiesta con Accept: text/markdown ottiene Markdown.
Portare gli agenti ai tuoi dati (Link Headers): cerca relazioni utili nell'header di risposta.
Dichiarare l’uso del contenuto (Content Signals): cerca una riga Content-Signal completa, che copra ai-train, search e ai-input.

I punti aperti mostrano il pulsante Copia il prompt per l’agente direttamente nella riga; i punti soddisfatti lo mostrano solo quando apri la riga, insieme al testo trovato. Per un punto aperto, il prompt descrive che cosa creare, mostra con curl lo stato attuale e indica un comando per verificare il risultato. Per un punto soddisfatto chiede al tuo assistente di coding di controllare l'esistente, cambiare solo ciò che serve e chiederti conferma prima di togliere una regola che non capisce. Le decisioni, come consentire o bloccare i crawler AI, restano a te, e alcuni prompt dei punti aperti propongono valori di esempio: decidi prima e leggi il prompt prima di incollarlo in Claude Code, Cursor, GitHub Copilot o ChatGPT. Poi premi Ricontrolla per rifare la scansione. I report restano nella cache fino a 24 ore, e Ricontrolla forza una nuova esecuzione (alcune volte all'ora).

SEOgrinder è onesto sul gruppo «Extra»: sono suggerimenti di singoli produttori, e un effetto su Google non è dimostrato. Lo strumento non misura nemmeno se ChatGPT, Gemini o Perplexity citino davvero il tuo marchio. Controlla la base tecnica: le macchine possono raggiungere e leggere la tua pagina?

Vale la pena?

Dipende da ciò che offre il tuo sito. Documentazione, pagine di consultazione, guide lunghe e basi di conoscenza sono il genere di contenuto che gli agenti richiamano per rispondere a una domanda concreta, e lì una versione Markdown pulita è utile. Per un piccolo negozio o un'attività locale con cinque pagine, il tempo è speso meglio sulle basi: testo presente nell'HTML senza JavaScript, un robots.txt che lascia entrare i bot di ricerca e una sitemap.

Per le funzioni AI di Google, Google afferma che non ci sono requisiti aggiuntivi per comparire in AI Overviews o AI Mode, né altre ottimizzazioni particolari; i dettagli sono nella documentazione di Google. Una versione Markdown, quindi, lì non è un requisito. Altri assistenti possono comportarsi diversamente, ma nessuno può promettere che un assistente AI nomini la tua pagina.

Errori frequenti

Nessun header Vary. Senza Vary: Accept, una cache o una CDN può servire la versione sbagliata al visitatore successivo.
Una cache a monte che ignora l'header. Prova dall'indirizzo pubblico, non solo contro il tuo server di origine.
Markdown per i browser. Se il tuo controllo tratta il carattere jolly */* come richiesta di Markdown, i visitatori vedono testo grezzo. Prova con un browser normale.
Nessun link canonical. La versione Markdown può allora essere trattata come pagina a sé. Abbiamo scelto l'header canonical al posto di noindex perché la versione negoziata sta sullo stesso indirizzo della pagina.
Una versione Markdown che dice altro. Mantieni il contenuto uguale a quello della pagina HTML, solo senza la cornice. Su come i motori di ricerca trattino le differenze tra le due non abbiamo una fonte, quindi tienile identiche.
Un file superato. Un index.md scritto a mano che elenca l'offerta dell'anno scorso porta gli agenti fuori strada. Generalo dalla fonte della pagina o mettilo nella tua lista di controllo.
Una pagina HTML vuota. Se l'HTML stesso non contiene testo finché non è stato eseguito JavaScript, il Markdown per gli agenti non risolve il problema per gli altri client, per esempio per le anteprime social. SEOgrinder segnala le pagine che vengono costruite solo nel browser; ne parliamo in crawler AI e JavaScript.

Domande frequenti

Il Markdown per agenti AI è un fattore di ranking?

Non ci sono prove. Consideralo un formato di consegna per le macchine, non una leva di ranking.

ChatGPT, Claude o Perplexity richiedono Markdown?

Cloudflare scrive che agenti di coding come Claude Code e OpenCode inviano già Accept: text/markdown. Per i crawler di ricerca dei grandi fornitori non esiste documentazione che lo richiedano; i dati di Radar di Cloudflare mostrano risposte Markdown a OAI-SearchBot, che non sono una prova di un header di richiesta. Quindi non è dimostrato.

Mi serve Cloudflare?

No. Cloudflare offre la conversione come funzione (in beta, nei piani Pro, Business ed Enterprise). Lo schizzo in Node qui sopra mostra che bastano poche righe di codice sul server, e le stesse regole si possono implementare in qualsiasi server o framework.

Meglio la negoziazione del contenuto o un indirizzo .md separato?

Puoi fare entrambe le cose. Un indirizzo fisso come /index.md è facile da linkare e da testare. La negoziazione mantiene un solo indirizzo per entrambi i destinatari. seogrinder.com offre entrambe le strade per la pagina iniziale.

I visitatori normali vedranno mai la versione Markdown?

Non se rispetti la regola sul carattere jolly: il Markdown viene inviato solo quando text/markdown è nominato esplicitamente e non ha un peso inferiore a text/html.

Il prossimo passo

Avvia la scansione gratuita in SEOgrinder e apri la scheda Preparazione all'IA. Guarda le tre righe Extra su Markdown, Link Headers e Content Signals e decidi se il tuo sito è del tipo che gli agenti leggono. Se lo è, copia il prompt per l'agente, fai fare la modifica al tuo assistente, controlla il risultato con curl e ripeti la scansione.