Convertire MD in PDF

Questa è la differenza rispetto a ogni altra conversione di documenti sul sito. Un file Word conosce la sua dimensione di pagina, i suoi margini e i suoi font; un file Markdown non conosce nulla di tutto ciò, perché il formato registra deliberatamente la struttura e lascia l'aspetto a qualunque cosa lo renderizzi.

Quindi ogni decisione sulla pagina — dimensione, margini, carattere tipografico, dove cade un'interruzione — la prende il convertitore, e nessuna di esse è nel file. È lo scambio che il Markdown fa, ed è di solito un buon affare: lo stesso documento diventa una pagina web, una presentazione e un PDF senza essere riscritto. Il costo emerge qui, perché un convertitore a cui non è stato insegnato a leggere il Markdown non ha nulla da renderizzare e ripiega sull'impostare i caratteri così come sono.

Ogni carattere del file arriva sulla pagina, in ordine, in un unico carattere tipografico. Una riga che dice ## Requisiti viene composta come ## Requisiti. Un elenco puntato scritto con un trattino resta una riga che inizia con un trattino. Un blocco delimitato porta ancora i suoi tre backtick sopra e sotto. Il grassetto conserva i suoi quattro asterischi. Nulla viene scartato e nulla viene interpretato, perché il motore documentale dietro questa coppia legge testo e non ha mai ricevuto un filtro Markdown.

Vale la pena essere precisi su cosa resta. Interruzioni di riga, righe vuote e rientri sono conservati esattamente, quindi un documento il cui valore sono i suoi comandi e la sua configurazione converte in qualcosa di utilizzabile. Un documento il cui valore è la gerarchia dei titoli no, e la risposta lì è renderizzare il Markdown nello strumento in cui è stato scritto — un'anteprima dell'editor, una build di sito statico, una pipeline di documentazione — e stampare il PDF da lì. Questa conversione serve a correggere il testo di un file, non a impaginarlo.

Un documento Markdown che mostra sei diagrammi non contiene sei diagrammi. Contiene sei percorsi, e le immagini vivono accanto ad esso su disco o su un server. Questo sorprende chi converte per la prima volta, ed è il motivo più comune per cui un PDF arriva con dei vuoti.

Il rimedio è far risolvere i percorsi prima di convertire. I percorsi relativi devono puntare a file che accompagnano davvero il documento; gli indirizzi web assoluti dipendono dal fatto che quel server sia raggiungibile. Se le immagini sono il punto del documento, questo è il passo da sistemare, non le impostazioni di conversione.

Moltissimi file Markdown si aprono con un blocco delimitato da tre trattini che contiene un titolo, una data e alcuni tag. I generatori di siti statici, gli strumenti di documentazione e le applicazioni per appunti leggono quel blocco come metadati e lo rimuovono prima di renderizzare qualsiasi cosa.

Questa conversione non conosce la convenzione e stampa il blocco come tutto il resto, quindi il PDF inizia con tre trattini e un elenco di coppie chiave-valore prima che il documento cominci. Cancellare il blocco prima di convertire è tutto il rimedio necessario, ed è meglio farlo su una copia in modo che l'originale continui a funzionare nello strumento che lo ha scritto.

La descrizione originale del Markdown del 2004 era informale, CommonMark è la specifica precisa che la maggior parte degli strumenti segue, e le tabelle a pipe, le liste di attività, le note a piè di pagina e il testo barrato che tutti usano sono estensioni sopra di essa. Quale di queste uno strumento implementi è normalmente la domanda che decide come esce un documento.

Non è la domanda su questa pagina. Qui non è implementato nulla di tutto ciò, né il nucleo stesso, quindi una tabella in stile GitHub e un titolo CommonMark vengono trattati allo stesso modo — come righe di testo. È almeno prevedibile: non c'è variante da indovinare né renderizzatore da testare, e ciò che si vede nel proprio editor con l'evidenziazione della sintassi spenta è ciò che il PDF conterrà.

Perché il destinatario non è chi scrive. Un cliente, un avvocato, una commissione o un responsabile della conformità vuole un documento che possa aprire, stampare, firmare intorno e archiviare — non un file che la sua macchina propone di aprire in un editor di codice, né un repository da navigare. I cancelletti viaggiano con esso, quindi questa è una copia fissa più che presentabile.

Un PDF congela anche lo stato. Un README cambia ogni settimana; un PDF di esso è ciò che era vero nel giorno in cui è stato allegato a qualcosa, esattamente ciò di cui hanno bisogno una revisione, una presentazione o un allegato contrattuale. Si continua a scrivere in Markdown e si esporta nel momento in cui qualcuno esterno ne ha bisogno.

HTML quando la destinazione è una pagina web o un sito di documentazione, dato che il Markdown è stato progettato come una scorciatoia per esso e la conversione è più vicina a una traduzione che a un rendering.

DOCX in una situazione specifica e comune: il destinatario accetterà solo un file Word e vuole aggiungere modifiche tracciate. Il Markdown non ha alcun flusso di revisione, quindi un documento che entra in un giro di commenti è meglio consegnarlo come DOCX e rileggerlo dopo — e il PDF è per la versione finita. Quella destinazione passa per lo stesso motore, quindi anche lì il markup arriva come testo; la differenza è che il revisore può correggere un titolo e in un PDF non si può.

A differenza della maggior parte delle conversioni su questo sito, questa gira su un server piuttosto che nel browser, perché richiede un vero motore documentale. Il file viaggia su una connessione cifrata, viene convertito in un ambiente isolato senza accesso a internet, e viene eliminato non appena il lavoro finisce.

Vale la pena dirlo apertamente piuttosto che sorvolare: per la maggior parte delle conversioni su Quinvert nulla lascia il dispositivo, ma questa coppia è una delle 89 che richiede il passaggio server perché LibreOffice, non un modulo del browser, fa il lavoro di impaginazione.