MarkItDown: convertire i documenti in Markdown per l'IA

Hai una cartella di documenti: preventivi in Word, un catalogo in Excel, tre PDF scaricati da un portale. E vorresti che l’agente li usasse per un lavoro vero. Il problema è che quei file non sono testo: sono contenitori, e per arrivare alle parole che contengono bisogna aprirli.

MarkItDown è un programma da terminale che fa esattamente questo, e niente altro: prende un documento e ne scrive fuori la versione in Markdown, cioè in testo semplice con i titoli, gli elenchi e le tabelle ancora riconoscibili. È di Microsoft, si installa con un comando, e la sua intera ragione di esistere sta in una riga della documentazione: convertire i file «per l’uso con gli LLM e le pipeline di analisi del testo».

In questo articolo vediamo perché conviene convertire un documento invece di passarlo all’agente così com’è, cosa la conversione conserva e cosa perde per strada, con due prove fatte sullo stesso contenuto, e come organizzare le cartelle in modo che fra sei mesi si capisca ancora quale file è l’originale.

Se Claude Code o Codex sono ancora parole nuove, i due articoli introduttivi sono Claude Code: cos’è, come funziona e cosa può fare e OpenAI Codex: cos’è e come usarlo dal terminale.

Markdown, il minimo che serve qui

Markdown è testo semplice in cui la struttura si vede a occhio nudo: un titolo è una riga che comincia con un cancelletto, il grassetto sta fra due asterischi, un elenco è una serie di righe che cominciano con un trattino. Nient’altro: nessun programma che lo apre, nessun formato binario.

# Piano di comunicazione 2026

Documento di lavoro, versione **2**.

## Obiettivi

* Aumentare le iscrizioni alla newsletter
* Ridurre il costo per contatto

Un file così si riconosce dall’estensione .md, si apre con qualunque cosa sappia mostrare del testo, e pesa quanto le parole che contiene.

È anche il formato in cui i modelli sono più a loro agio, e per due motivi che qui bastano: ci sono cresciuti dentro, perché una quota enorme del testo tecnico degli ultimi vent’anni è scritta così, e la struttura è dichiarata invece che disegnata. Il cancelletto dice che quella riga è un titolo, mentre in un PDF lo si deduce dal fatto che è più grande. È la ragione per cui uno strumento come MarkItDown esiste e per cui lo firma Microsoft: la sua documentazione dice che i modelli mainstream «parlano» nativamente Markdown, e che le sue convenzioni sono molto efficienti in termini di token, l’unità con cui si misura quanto testo entra in una conversazione.

Se ti interessa la storia lunga, cioè come un formato inventato nel 2004 per non scrivere HTML a mano sia finito vent’anni dopo a fare da lingua all’IA, sta in Markdown: cos’è, e perché è diventato la lingua dell’IA. Per il resto di questo articolo bastano le righe qui sopra.

Perché non dare direttamente il .docx all’agente

Qui sta la domanda vera, e la risposta si vede meglio con un documento in mano che con una spiegazione. Prendo un piano di comunicazione finto (un titolo, un paragrafo, un elenco di tre voci, una tabella di budget, un collegamento) e lo salvo in Word.

Un .docx non è un documento: è un archivio. Se lo apri con gli strumenti del terminale, la prima cosa che vedi è PK, la firma dei file compressi. Dentro ci sono undici file separati:

word/document.xml       il testo, dentro migliaia di tag
word/styles.xml         gli stili
word/numbering.xml      come sono numerati gli elenchi
word/theme/theme1.xml   i colori e i caratteri
word/fontTable.xml      i caratteri usati
docProps/core.xml       autore, date, revisione
...e altri cinque

Il testo vero sta in word/document.xml, annegato in marcatori come <w:p><w:r><w:rPr><w:b/></w:rPr><w:t>. Per quel documento di poche righe, quel solo file è 10.723 caratteri. Lo stesso contenuto, convertito in Markdown, ne occupa 524: venti volte meno, e ci sono ancora dentro il titolo, il grassetto, l’elenco, la tabella e il collegamento.

La prima conseguenza è che l’agente si rifiuta. Il gesto con cui Claude Code apre un file su un .docx risponde così, e non è un capriccio:

This tool cannot read binary files. The file appears to be a binary .docx file.

Un agente da terminale non è bloccato del tutto: sa scompattare l’archivio e leggersi l’XML, se glielo chiedi. Solo che a quel punto sta facendo a mano, di corsa e ogni volta da capo, il lavoro che uno strumento di conversione fa una volta sola e meglio, pagando venti volte il testo in token e riempiendo la conversazione di roba che non ti serve.

Con i PDF la faccenda è diversa e vale la pena dirlo con precisione, perché è il punto in cui si sente ripetere una cosa non vera. Claude Code un PDF lo apre davvero, pagina per pagina. Ma lo guarda come si guarda una fotografia: costa parecchio, non lascia niente sul disco, e la volta dopo si ricomincia.

Il vantaggio della conversione, quindi, non è «l’agente altrimenti non ce la fa». È tutto in quello che ti resta in mano dopo:

1. un file che puoi leggere tu. Il passaggio delicato, cioè capire cosa si è perso e cosa si è spostato, avviene una volta, in un file che apri e controlli con i tuoi occhi. Se l’agente legge il documento da solo, quel passaggio avviene dentro la conversazione, dove non lo vedi e non lo puoi correggere;
2. un risultato stabile. Lo stesso file convertito due volte dà lo stesso testo. La lettura fatta al volo dentro una conversazione no: cambia con il modello, con la lunghezza della chat, con quanto contesto è già occupato;
3. un file che si comporta come un file. Lo cerchi con grep, lo metti sotto controllo di versione, lo apri fra un anno, lo passi a un altro agente. Un documento «letto» in una conversazione esiste finché dura quella conversazione;
4. una spesa che paghi una volta. Dieci domande sullo stesso contratto sono dieci letture del PDF, oppure una conversione e dieci domande su un file di testo;
5. la possibilità di guardare cosa esce. Se il documento contiene dati di un cliente, il file convertito lo puoi aprire, sfoltire e anonimizzare prima che finisca in una conversazione. È il tema del capitolo sul materiale che non è tuo, applicato al gesto più banale che c’è.

E quando invece non conviene convertire? Quando il documento è uno solo, lo guardi una volta e non ci torni. Quando quello che ti interessa è come è fatta la pagina, per un volantino, un layout, una firma: la disposizione è proprio la cosa che la conversione butta via. E quando il PDF è la scansione di un foglio di carta: lì dentro non c’è testo, ci sono pixel, e MarkItDown da solo non ha nulla da estrarre.

Cosa conserva e cosa perde: due prove sullo stesso testo

Questa è la sezione da leggere prima di fidarsi. Ho preso lo stesso contenuto e l’ho salvato in due formati, poi ho convertito entrambi. I risultati non si somigliano per niente.

Dal .docx, il testo esce con la struttura intatta: i titoli sono titoli, il grassetto è grassetto, l’elenco è un elenco, la tabella è una tabella e il collegamento porta ancora al suo indirizzo.

# Piano di comunicazione 2026

Documento di lavoro, versione **2**.

## Obiettivi

* Aumentare le iscrizioni alla newsletter
* Ridurre il costo per contatto

## Budget per canale

|  |  |  |
| --- | --- | --- |
| Canale | Budget | Contatti attesi |
| Ricerca a pagamento | 4.000 € | 320 |
| Social | 2.500 € | 180 |

Guarda però la prima riga della tabella: è vuota. La riga delle intestazioni è scivolata in mezzo ai dati, perché Markdown pretende una riga di intestazione e il documento di partenza non gliene dichiarava una. È un difetto piccolo e tipico, e nessuno se ne accorge, tranne l’agente, che poi tratta «Canale» come un valore. Ecco perché il file convertito si guarda.

Dallo stesso contenuto in PDF, invece:

Piano di comunicazione 2026

Obiettivi

• Aumentare le iscrizioni alla newsletter

Budget per canale

Canale

Budget Contatti attesi

Ricerca a pagamento 4.000 € 320

Social

2.500 € 180

I titoli non sono più titoli: sono righe di testo come le altre, e nessuno sa più che «Obiettivi» apriva una sezione. Il grassetto è sparito. Il collegamento è diventato la parola che lo conteneva. E la tabella si è sfaldata in colonne appiccicate una sotto l’altra: Social da una parte, 2.500 € dall’altra. Il numero e la riga a cui apparteneva non stanno più insieme, e un agente che legge quel testo può accoppiarli male senza avere alcun modo di accorgersene.

La ragione è nel formato, non nello strumento. Un .docx dichiara la struttura: dice «questo è un titolo di secondo livello», «questa è una cella». Un PDF descrive dove appoggiare i caratteri sulla pagina, e basta: la tabella che vedi è un effetto ottico, prodotto da testo allineato bene. Chi converte un PDF deve indovinare a posteriori cosa era una tabella, e a volte indovina, a volte no.

La regola pratica che ne esce: se puoi scegliere il formato di partenza, chiedi il .docx, l’.xlsx o l’.html invece del PDF. Un documento nato in Word e salvato in Word conserva tutto; lo stesso documento «stampato» in PDF ha già buttato via metà delle informazioni prima ancora che tu ci provi.

Chi fa cosa: tu e l’agente

Prima dei comandi, la divisione del lavoro. Questa non è una guida da trascrivere: è materiale da dare in mano all’agente, tenendoti i pezzi che restano tuoi.

Quello che può fare l’agente. Installare lo strumento, creare le cartelle, convertire i file, riportarti quali conversioni sono fallite e perché. È lavoro ripetitivo su file che stanno sul tuo computer: esattamente il suo mestiere.

Quello che resta a te. Tre cose, e non sono negoziabili. Decidere quali documenti entrano nel lavoro, perché l’agente non sa quale contratto è quello buono e quale la bozza di due anni fa. Guardare il testo convertito almeno per i documenti che contano, perché è il solo momento in cui un errore di conversione si vede ancora. E decidere cosa può uscire da lì, se dentro ci sono nomi, compensi o dati di clienti.

La richiesta da incollare, aprendo l’agente nella cartella dove hai i documenti:

Installa MarkItDown in un ambiente isolato e usalo per convertire in Markdown i
documenti di questa cartella.

Prima di partire: crea `originali/`, `testo-convertito/` e `output/`, e sposta i
documenti in `originali/`. Gli originali non si modificano e non si cancellano
mai.

Converti un file solo per cominciare, il più semplice, e fermati: voglio
guardare il risultato prima che tu faccia gli altri.

Poi convertili tutti, con lo stesso nome dell'originale e l'estensione .md, e
alla fine elencami: quanti file hai convertito, quali sono falliti e con che
errore, e quali conversioni ti sembrano sospette (tabelle sfaldate, documenti
usciti quasi vuoti, testo fuori ordine).

Le quattro clausole non sono cortesia, e valgono ben oltre questo compito. Gli originali non si toccano ti garantisce che, qualunque cosa succeda, c’è ancora una copia buona da cui ripartire. Converti un file solo e fermati ti fa scoprire su un file che il risultato non va bene, invece che su duecento. Stesso nome, estensione diversa rende ovvio a colpo d’occhio quale convertito viene da quale originale. Elencami quelli sospetti è la più importante: chiede all’agente di dirti dove non è sicuro, invece di consegnarti una cartella di file che sembrano tutti riusciti.

E cosa controlli, alla fine? Che il numero dei file convertiti torni con quello degli originali; che un documento lungo non sia diventato un file di tre righe; che le tabelle abbiano ancora la forma di tabelle.

Come si installa, e cosa succede sotto

I comandi qui sotto probabilmente li eseguirà l’agente. Vale comunque la pena sapere che aspetto hanno, perché sono quelli che ritroverai negli errori.

MarkItDown è un programma Python e richiede Python 3.10 o successivo. Si installa così:

pipx install 'markitdown[all]'

Due dettagli in quella riga. pipx installa i programmi da terminale ognuno nel suo ambiente separato, così non si pestano i piedi fra loro né con il Python di sistema: è la stessa convenzione usata nella ricetta su Google Analytics. E [all] chiede tutti i lettori di formato disponibili; le virgolette servono perché altrimenti il terminale prova a interpretare le parentesi quadre da sé.

Se preferisci tenere l’installazione leggera, i lettori si scelgono uno per uno come markitdown[pdf,docx,pptx], e i gruppi disponibili sono pdf, docx, pptx, xlsx, xls, outlook, audio-transcription, youtube-transcription, più quelli per i servizi Azure. Il consiglio è installare tutto la prima volta: la differenza è qualche decina di megabyte, e il giorno che ti arriva un .epub non devi tornare qui.

La conversione di un file è una riga sola:

markitdown originali/piano.docx -o testo-convertito/piano.md

Senza -o il risultato esce a schermo, e lo puoi incanalare dove vuoi. È utile sapere che funziona anche così, perché è il modo in cui te lo vedrai scritto nella documentazione:

markitdown originali/piano.docx > testo-convertito/piano.md

Dove mettere i file

Tre cartelle, e ognuna con una regola sola. È la stessa impostazione delle altre ricette del sito, e serve a distinguere ciò che hai ricevuto da ciò che hai prodotto:

lavoro/
├── originali/          i documenti come ti sono arrivati, non si toccano
├── testo-convertito/   il .md prodotto dalla conversione, si può rigenerare
└── output/             quello che produci tu con l'agente

originali/ è sacra: se un giorno la conversione va storta, o esce uno strumento che converte meglio, riparti da lì. testo-convertito/ è materiale usa e getta: si può cancellare e rifare in qualunque momento, e per questo non ha senso metterla sotto controllo di versione né conservarla con cura. output/ è dove finisce il lavoro vero, che è l’unica cosa che quella cartella non può rigenerare da sola.

La cosa che sembra pedante e non lo è: nessun file cambia cartella. Il giorno che ti chiedono da dove è uscito quel numero, la risposta è un percorso, non un ricordo.

Gli altri formati che gestisce

Word e PDF sono i casi frequenti, ma la lista è più lunga di quanto ci si aspetti. Questi sono i lettori presenti nella versione 0.1.5, con quello che producono davvero:

Due avvertenze che la documentazione non rende evidenti, e che risparmiano mezz’ora di sospetti.

Sulle immagini non c’è OCR. Il riepilogo del progetto nomina l’OCR, ma il lettore delle immagini, da solo, tira fuori i dati tecnici del file (data, macchina, dimensioni) e nient’altro. Per avere una descrizione di cosa si vede devi collegare un modello multimodale; per leggere il testo dentro un’immagine servono un’estensione a parte o i servizi Azure. Se converti la scansione di una fattura aspettandoti i numeri, torni indietro con la data di scatto.

Il .doc vecchio non è il .docx. Il lettore accetta solo .docx, quello con la x. Se hai file degli anni Duemila, prima vanno riaperti e risalvati nel formato nuovo.

Darlo all’agente come strumento, invece che come comando

C’è una seconda strada, che cambia il modo di lavorare. Lo stesso progetto pubblica markitdown-mcp: la stessa conversione, confezionata come strumento che l’agente può usare da solo, senza passare da un comando.

Un server MCP è un piccolo programma che sta fra l’agente e qualcosa che l’agente da solo non sa fare; l’idea è spiegata per esteso nella ricetta su Google Analytics. Qui il servizio è uno solo, si chiama convert_to_markdown, e accetta sia un file sul tuo computer sia un indirizzo web.

La differenza pratica è nel modo in cui chiedi le cose. Con il comando dici «converti questi file, poi leggili». Con lo strumento collegato dici «guarda il preventivo che sta in quella cartella e dimmi se le condizioni di pagamento sono cambiate rispetto all’anno scorso», e la conversione avviene per strada, senza che nessuno dei due la nomini.

Le due strade non si escludono. Il comando è più adatto quando devi convertire molti file una volta sola e vuoi vedere cosa è successo; lo strumento collegato è più comodo quando i documenti sono pochi e la conversione è un passaggio in mezzo a un lavoro più grande.

Cosa questo strumento non fa

Non capisce il documento. Non riassume, non estrae le clausole, non ti dice se il contratto è buono. Toglie l’involucro: il ragionamento resta lavoro dell’agente, e la decisione resta tua.

Non conserva l’impaginazione. Colonne, riquadri, intestazioni, numeri di pagina, colori: tutto questo sparisce, ed è intenzionale. Se quello che ti serve è l’aspetto della pagina, questo è lo strumento sbagliato.

Non legge le scansioni. Un PDF che è la fotografia di un foglio esce vuoto o quasi. Servono strumenti di riconoscimento del testo, che sono un mestiere a parte.

Non protegge i tuoi dati. Converte in locale, e questo è un vantaggio reale e il documento non esce dal computer per essere convertito. Ma il file che ne risulta, se poi lo dai a un agente, viaggia come qualunque altra cosa scrivi in una conversazione.

Domande frequenti

Serve saper scrivere in Markdown?

No. Il Markdown qui lo produce lo strumento e lo legge l’agente: a te serve solo riconoscere un titolo, un elenco e una tabella quando li guardi, e ci vogliono i due minuti dell’apertura di questo articolo.

Funziona con Codex, o solo con Claude Code?

MarkItDown non sa niente di agenti: produce un file di testo su un disco. Qualunque agente in grado di leggere un file legge il risultato. Cambia soltanto il file di configurazione, se scegli la strada dello strumento collegato.

La conversione modifica i miei documenti originali?

No: legge e scrive un file nuovo. La regola di tenere gli originali in una cartella a parte non serve a proteggerli dallo strumento, serve a proteggerli da noi, dal riordino distratto di sei mesi dopo.

Posso convertire una pagina web?

Sì, passando l’indirizzo invece del percorso di un file, e la pagina esce ripulita di menu e barre laterali. Attenzione però alle pagine che si costruiscono nel browser mentre le guardi: di quelle si porta via poco o niente.

E se un file non si converte?

I motivi frequenti sono tre: manca il lettore per quel formato, cosa che capita installando senza [all]; il file è protetto da password; oppure è un .doc vecchio scambiato per un .docx. L’errore che compare a schermo dice quale dei tre.

Quanto è affidabile su un documento lungo?

Su .docx e .xlsx, molto: la struttura è dichiarata nel file e viene ricopiata. Su PDF lunghi, dipende dal PDF, e il modo di scoprirlo non è fidarsi: è aprire il convertito e leggere un paio di punti a caso, uno all’inizio e uno in fondo.

Da dove continuare

Se vuoi vedere dei documenti convertiti diventare qualcosa, il passo successivo naturale è la ricetta su come creare le slide per una lezione: lì il materiale di partenza si dà per pronto, e questo articolo è il pezzo che mancava prima.

Se invece è il formato in sé a incuriosirti, e come mai le IA ci si trovino così bene, c’è Markdown: cos’è, e perché è diventato la lingua dell’IA.

Per capire perché conta tanto cosa entra nella conversazione e in che forma, il posto giusto è Chi hai dall’altra parte. E se i documenti su cui stai lavorando sono di qualcun altro, il terzo progetto del libro parte esattamente da lì.

Puoi anche iscriverti agli aggiornamenti per ricevere i prossimi articoli.

Fonti ufficiali

• MarkItDown, il progetto su GitHub
• markitdown-mcp, lo strumento per gli agenti
• Markdown, la pagina originale di John Gruber
• RFC 7763, il tipo text/markdown
• Model Context Protocol