Che cos’è un file MD?

MD è un formato di testo semplice che si apre in qualsiasi editor. Si usa per la modifica e spostare dati fra programmi.

L’estensione è .md e il nome per esteso è Markdown. Contano entrambi meno di ciò che il file può contenere, ed è di questo che parla il resto della pagina.

Risale al 2004. La specifica è CommonMark.

L’età serve saperla per un motivo pratico: più un formato è vecchio, più programmi hanno avuto tempo di impararlo.

È pubblicata per intero, quindi la si può implementare partendo dal documento invece che per osservazione: è per questo che il formato compare in così tanti programmi, ed è per questo che file scritti vent’anni fa si aprono ancora. Una specifica pubblicata però non è la stessa cosa di una esente da royalty: dove un formato incapsula un codec, le licenze sui brevetti restano una questione a parte che lo standard non risolve.

Visual Studio Code, Obsidian e Typora lo leggono, e così fanno quasi tutti i programmi dello stesso tipo.

Quando un file non si apre, il formato è raramente il problema: più spesso è il programma a essere più vecchio di lui. Convertire in qualcosa di più vecchio è la via d’uscita affidabile, ed è a questo che serve il resto di questo sito.

Nessun browser lo legge.

È di gran lunga il motivo più comune per convertirlo: non che il formato sia scadente, ma che il posto in cui vuoi mostrare il file non sappia leggerlo.

MD è pensato per essere aperto e modificato. Tieni il file in questo formato per tutto il tempo in cui il lavoro va avanti, ed esporta da lì ogni volta che serve una copia finita.

Il Markdown è nato perché scrivere HTML a mano è faticoso e scrivere in un elaboratore di testi produce un file che nessuno può confrontare riga per riga. È un pugno di convenzioni già usate nell’email in testo semplice prima ancora di avere un nome: un cancelletto a inizio riga marca un titolo, due asterischi intorno a una parola la mettono in grassetto, un trattino apre un elenco puntato.

La cosa importante è che l’originale resta leggibile per chiunque non abbia mai sentito parlare del formato. Ecco perché si è imposto nella documentazione tecnica: un README, un changelog o un appunto scritto in Markdown è un file di testo, entra nel controllo di versione, due persone lo modificano e uniscono il risultato, e chi revisiona legge le differenze senza dover aprire nulla.

La descrizione originale del 2004 era informale e lasciava moltissimo indeciso, quindi ogni implementazione ha riempito i vuoti a modo suo. CommonMark è il serio tentativo di scrivere una specifica precisa ed è ciò che seguono la maggior parte degli editor attuali. GitHub Flavored Markdown è CommonMark più un pugno di aggiunte, e si rivela essere la versione che quasi tutti hanno effettivamente usato.

L’aggiunta che genera più confusione sono le tabelle con barre verticali: non fanno parte di CommonMark, sono un’estensione di GitHub supportata anche da molti editor e generatori di siti statici, ma assente nelle implementazioni rigorose. Una tabella che appare perfetta in un repository e diventa una riga di barre altrove non è un file rotto: è un file che usa un’estensione che l’altro strumento non implementa. Liste di attività, testo barrato e link automatici stanno nella stessa categoria.

Molti file iniziano con un blocco delimitato da tre trattini che contiene qualcosa come un titolo, una data e un elenco di tag. Questo è il front matter — di solito YAML, a volte TOML o JSON — e non è affatto Markdown. I generatori di siti, le app di appunti e i costruttori di documentazione lo leggono come metadati del documento e lo rimuovono prima di mostrare qualsiasi cosa.

Uno strumento che non ne conosce l’esistenza lo mostra come testo letterale in cima alla pagina. Se un documento convertito inizia con tre trattini e un elenco di coppie chiave-valore, è successo questo, e cancellare il blocco prima di convertire è tutto ciò che serve.

Non c’è dimensione della pagina, né margini, né tipografia, né interlinea, né interruzione di pagina, né piè di pagina. Non è una mancanza ma l’impostazione stessa: il file descrive struttura — questo è un titolo, questa una citazione, questo codice — e lascia l’aspetto a ciò che lo renderizza. Lo stesso documento diventa pagina web, PDF e presentazione senza riscrivere una riga.

Non ha nemmeno commenti, né tracciamento delle modifiche, né modo di dire che questo paragrafo è alla terza revisione. Di questo si occupa il controllo di versione, e lo fa meglio; è lo scambio che il formato accetta. Se serve un flusso di revisione con firme e non una cronologia, un elaboratore di testi è lo strumento onesto.

Un file Markdown che mostra sei diagrammi non contiene alcun diagramma: contiene sei percorsi, e le immagini stanno accanto sul disco o su un server. Spostate il file senza la cartella che lo circonda e spariscono tutte.

Questo pesa nella conversione, e qui più che altrove: la conversione in PDF di questo sito non tenta nemmeno di seguire quei percorsi, quindi il riferimento viene stampato così come è stato scritto, con il suo punto esclamativo, il testo alternativo fra parentesi quadre e il percorso fra parentesi tonde. E pesa di nuovo inviandolo per email: mandare un .md isolato significa mandare lo scheletro. Se le immagini sono metà del messaggio, apritelo dove lo avete scritto ed esportate il PDF da lì.

Di questo formato, questo sito offre esattamente una conversione: a PDF. La esegue LibreOffice, e LibreOffice non gira nel browser, quindi il file viene inviato al nostro server invece di restare sul vostro computer. È una delle poche vie del sito che funzionano così e vale la pena dirlo senza abbellimenti.

Da qui derivano due numeri precisi. Il limite per file nelle conversioni server è di 25 MB, non i 100 MB di quelle che girano nel browser, e c’è un tetto di cento conversioni server per visitatore al giorno, che si azzera a mezzanotte UTC. Il file viene salvato in una cartella temporanea appena creata, con un nome generico — il vostro non tocca il disco —, e quella cartella viene cancellata al termine, anche quando la conversione fallisce.

Il markup viene stampato, non interpretato. La suite per ufficio che fa il lavoro non ha un filtro di importazione per Markdown e il contenitore non installa alcuno strumento di documentazione che potrebbe renderizzarlo prima, quindi il file viene composto come il testo semplice che è: una riga che dice ## Requisiti esce come ## Requisiti, un elenco puntato scritto con un trattino esce come una riga che inizia con un trattino, e un blocco di codice conserva i suoi tre apici sopra e sotto.

Ciò che invece si conserva esattamente sono gli a capo, le righe vuote e l’indentazione, quindi un documento il cui valore sta nei suoi comandi e nella sua configurazione diventa qualcosa di perfettamente utilizzabile, mentre uno il cui valore sta nella gerarchia dei titoli no. In quel caso, aprite il file nello strumento in cui lo avete scritto e stampate il PDF da lì. La composizione avviene con font sostitutivi di metrica compatibile, cosa che qui quasi non fa male: il Markdown non porta font al suo interno e non c’è nulla da sostituire male.

Basta qualsiasi editor di testo — il Blocco note, TextEdit, nano — perché il file è testo. Questo è tutto il suo fascino, ed è il motivo per cui un documento scritto nel 2004 si apre oggi senza avere nulla di installato.

Gli editor dedicati aggiungono un’anteprima dal vivo, molto utile mentre si scrive e del tutto irrilevante per il file. Visual Studio Code, Obsidian e Typora la mostrano durante la digitazione e nessuno di loro salva nulla che gli altri non possano leggere. Sceglierne uno è una preferenza e non un compromesso, cosa che non si può dire di quasi nessun altro formato di documento.