Stampa Markdown con eleganza

Il modo più veloce per provare mdprint è iniziare a scrivere nell'editor sulla home page. Si carica con un documento di esempio che esercita ogni funzione - tabelle, codice, matematica, diagrammi - così vedi subito com'è una pagina finita. Cancella l'esempio e scrivi il tuo contenuto, oppure incollalo da dove l'hai scritto.

Se hai già un file Markdown sul computer, hai due modi per caricarlo. Il primo è trascinarlo dal gestore di file e rilasciarlo sul pannello dell'editor. Durante il trascinamento apparirà un'evidenziazione attorno all'area di rilascio. Rilascia il file e l'editor si riempie del suo contenuto. Il secondo è cliccare il pulsante Importa nella barra degli strumenti e selezionare il file nel selettore. Entrambi i metodi leggono il file localmente - non viene caricato nulla.

mdprint accetta file .md, .markdown e .txt. L'estensione .txt è utile per documenti scritti in Markdown ma salvati con un'estensione generica da un altro strumento. Se provi a importare un file con un'altra estensione, mdprint mostrerà un errore e lascerà intatto il contenuto attuale.

Se non hai mai scritto Markdown, le regole sono poche e si imparano in cinque minuti. Scrivi testo semplice e quattro caratteri fanno la maggior parte del lavoro. Il simbolo # all'inizio di una riga crea un titolo - un # per il più grande, sei ###### per il più piccolo. I simboli * e _ attorno a una parola la rendono corsiva con uno per lato e in grassetto con due. Il simbolo - o * all'inizio di una riga crea un punto elenco. Indenta di due spazi per annidare un punto sotto un altro.

Il codice si gestisce con i backtick. Un backtick per lato di una frase la formatta come `codice inline`. Tre backtick su una riga da soli aprono un blocco di codice e altri tre lo chiudono. Se metti il nome di un linguaggio subito dopo i tre backtick di apertura (```python, ```typescript, ```sql), il blocco di codice riceve l'evidenziazione di sintassi in quel linguaggio. Senza indicazione di linguaggio, l'evidenziatore prova a indovinare dal contenuto, cosa che di solito funziona con i linguaggi popolari.

Link e immagini usano entrambi parentesi quadre e tonde. Un link è [il testo che vedi](l'URL). Un'immagine è la stessa cosa con un punto esclamativo davanti: . Quando stampi in PDF, gli URL di immagini che puntano a server pubblicamente accessibili verranno recuperati e incorporati. Le immagini sulla tua macchina locale o dietro autenticazione non verranno rese - mettile direttamente nell'editor come URL data base64 se ti servono inline.

Le tabelle sono l'unica parte di Markdown che sembra fastidiosa nella sorgente ma viene resa in modo pulito. Una riga di intestazione, una riga separatrice di trattini e una o più righe di dati, tutte separate da barre. Le colonne non devono essere allineate nella sorgente - il renderer gestisce la spaziatura. Aggiungi i due punti a una o entrambe le estremità dei trattini nella riga separatrice per controllare l'allineamento: :--- per sinistra, ---: per destra, :---: per centrato.

Le equazioni matematiche usano la sintassi TeX racchiusa tra simboli del dollaro. Un dollaro per lato dà matematica inline: $a^2 + b^2 = c^2$. Due dollari su righe proprie danno un'equazione display, centrata sulla propria riga e più grande. Tutti i comandi matematici LaTeX che ti aspetteresti - \frac, \int, \sum, \sqrt, lettere greche, matrici, il set di simboli AMS - funzionano perché mdprint usa KaTeX, che implementa la stessa sintassi.

I diagrammi usano la sintassi Mermaid dentro un blocco di codice delimitato con etichetta mermaid. Il diagramma più semplice è un flusso: apri con graph LR (sinistra-destra) o graph TD (alto-basso), poi scrivi i nodi collegati da frecce. Mermaid supporta anche diagrammi di sequenza (flusso di messaggi tra attori nel tempo), diagrammi di Gantt (tempistiche di progetto con dipendenze), diagrammi di classe (relazioni tra oggetti) e diagrammi di stato (macchine a stati). La documentazione di Mermaid ha esempi per ogni tipo.

Le note a piè di pagina ti permettono di mantenere leggibile la prosa allegando citazioni dettagliate o digressioni. Segna una nota nel tuo testo con [^1] (il numero può essere qualsiasi - vengono rinumerate in uscita). Da qualche altra parte del documento, definisci la nota con [^1]: contenuto della nota. mdprint raccoglie tutte le note alla fine del documento stampato e aggiunge riferimenti di ritorno che collegano ogni nota al punto in cui compare nel testo.

Se il tuo documento è lungo, inserisci il testo letterale [[toc]] nella sorgente dove vuoi che appaia un indice. mdprint lo sostituisce con una lista annidata di link a ogni H2 e H3 del documento. Nel PDF stampato, lo stesso indice diventa una struttura di navigazione utilizzabile dai lettori PDF.

Apri il pannello Impostazioni dalla barra degli strumenti per controllare come viene generato il tuo PDF. Il formato pagina ha due opzioni: A4 (lo standard fuori dal Nord America) o Letter (lo standard nel Nord America). L'orientamento alterna tra verticale e orizzontale - orizzontale è utile per documenti con tabelle o diagrammi larghi. I margini offrono tre preimpostazioni: stretti danno più area utile per contenuto denso, normali sono la via di mezzo convenzionale, larghi lasciano spazio per annotazioni a mano su una copia stampata.

L'editor ha temi chiaro e scuro propri, indipendenti dal resto della pagina. L'interruttore nella barra degli strumenti li alterna. L'anteprima e l'uscita di stampa restano comunque in modalità chiara, perché gli sfondi chiari sono quelli che si stampano bene su carta.

Se usi regolarmente lo stesso insieme di opzioni, la tua ultima selezione viene ricordata localmente e applicata automaticamente la volta successiva che apri mdprint nello stesso browser.

Il pulsante Stampa apre la finestra di stampa nativa del tuo browser. Da lì, ogni sistema operativo moderno offre Salva come PDF come destinazione - Chrome, Firefox, Safari ed Edge lo supportano su macOS, Windows e Linux. Passare per la finestra di stampa dà più controllo: puoi scegliere qualsiasi stampante, vedere l'anteprima di ogni pagina, cambiare l'orientamento per pagina se il driver lo permette e, su alcune stampanti, cambiare cassetti carta o pinzatura.

Il pulsante Scarica PDF salta la finestra di stampa e genera un file PDF direttamente nel browser, poi avvia un download. Usa le tue Impostazioni attuali (formato pagina, orientamento, margini) per formattare l'uscita. Questa via è più veloce quando sai esattamente cosa vuoi e non ti serve la flessibilità della finestra di stampa. Funziona rendendo la pagina come immagine ad alta risoluzione e inserendo quell'immagine nel PDF, così il risultato corrisponde sempre a ciò che vedi sullo schermo. Il compromesso: poiché la pagina diventa un'immagine, il testo in questo PDF non è selezionabile né ricercabile.

Le due vie differiscono per ciò che finisce dentro il file. Salva come PDF, tramite il pulsante Stampa, mantiene il testo come testo: resta selezionabile e ricercabile, resta nitido a qualsiasi zoom e i diagrammi restano vettoriali. Scarica PDF è invece un'istantanea immagine con un clic, quindi è rapida e precisa al pixel, ma il testo non è selezionabile. Usa Salva come PDF quando vuoi testo selezionabile o il risultato più nitido a qualsiasi zoom; usa Scarica PDF quando vuoi solo una copia rapida ed esatta di ciò che è sullo schermo senza aprire la finestra di stampa.

Interruzioni di pagina in punti scomodi. mdprint evita di rompere dentro blocchi di codice, tabelle e diagrammi, ma non tenta di indovinare per la prosa. Se un titolo finisce in fondo a una pagina con il contenuto della sezione su quella successiva, la soluzione più semplice è aggiungere qualche frase prima o dopo per spingere il titolo. Non c'è una sintassi manuale di interruzione di pagina in V1 - aggiungerla è nella lista V2.

Le immagini non appaiono nel PDF. La causa più comune è un URL di immagine che punta al tuo file system locale (file://) o a un server che non consente l'accesso cross-origin. Incorpora l'immagine come URL data direttamente nella sorgente Markdown, oppure caricala su un host di immagini che permetta l'accesso pubblico in lettura. Imgur, i server user-content di GitHub e la maggior parte dei CDN funzionano.

La matematica non viene resa. Controlla la sorgente per simboli del dollaro non sfuggiti nel testo normale - un $ vagante può iniziare un'area matematica che si mangia il resto del paragrafo. Se ti serve un simbolo del dollaro letterale nella prosa, sfuggilo: \$. Se la sintassi matematica è corretta ma l'equazione comunque non viene resa, il comando LaTeX potrebbe non essere nell'elenco supportato di KaTeX - la documentazione di KaTeX ha un riferimento completo.

Il diagramma è vuoto. Mermaid è rigoroso con la sintassi. Gli errori più comuni sono uno spazio mancante dopo graph LR, un ID di nodo che contiene uno spazio (usa camelCase o underscore) o una freccia che punta a un nodo non definito. Apri la console di sviluppo del browser - Mermaid registra un messaggio di errore specifico quando il parsing fallisce.

Le tabelle vanno a capo in modo strano. Se una tabella è più larga della pagina, mdprint la ridimensiona per farla rientrare. Per tabelle molto larghe, passa all'orientamento orizzontale nelle Impostazioni, o ristruttura la tabella come lista. Il PDF non gestisce lo scroll orizzontale come fa il web.

Usa le scorciatoie da tastiera. Cmd+P (o Ctrl+P su Windows e Linux) apre la finestra di stampa. Cmd+S (Ctrl+S) attiva Scarica PDF. Le scorciatoie native del browser per cercare (Cmd+F), ricaricare (Cmd+R) e zoom (Cmd+più/meno) funzionano tutte normalmente - non vanno in conflitto con mdprint.

Inizia ogni documento con un H1. Il primo H1 diventa il nome di file PDF suggerito, il titolo del documento per l'accessibilità e il titolo prominente in cima alla pagina stampata. Se inizi con H2 o inferiore, il nome di file ricade su 'document.pdf' e dovrai rinominarlo manualmente dopo il download.

Incorpora le immagini come URL data quando la privacy conta. Se non vuoi che un lettore PDF vada a prendere immagini da un server remoto all'apertura del file, converti l'immagine in URL data base64 e incorporala direttamente. La maggior parte dei sistemi operativi ha uno strumento integrato o dedicato per questa conversione. Il file risultante è più grande, ma totalmente autoconsistente.

Usa le liste di attività per checklist stampate. Se produci una checklist cartacea - lista bagagli, checklist di spedizione, procedura passo passo - usa la sintassi delle liste di attività Markdown con - [ ]. Le caselle si stampano come quadrati da spuntare con una penna.

Combina mermaid e codice nella documentazione tecnica. Un pattern comune è mostrare un flusso di un processo seguito dal codice che lo implementa. Markdown permette entrambi nello stesso file e mdprint li rende in modo che si stampino in modo pulito affiancati.

Cmd+P o Ctrl+P - apri la finestra di stampa.

Cmd+S o Ctrl+S - scarica come PDF.

Cmd+B o Ctrl+B nell'editor - grassetto sul testo selezionato.

Cmd+I o Ctrl+I nell'editor - corsivo sul testo selezionato.

Cmd+/ o Ctrl+/ nell'editor - alterna il commento per la riga corrente (commento HTML in contesto Markdown).

Esc nell'editor a schermo intero - esci dallo schermo intero.