Blog

La prima volta che ho incontrato Markdown è stato subito colpo di fulmine.
A distanza di anni, lo uso per tutto, dagli appunti alla documentazione ufficiale.

cit. Marco Bellezza

Scenario: stai scrivendo un documentino per spiegare ai tuoi colleghi una semplice procedura, oppure un breve post o un commento un po' lungo su una issue in GitHub.

Apri un banale Blocco note e inizi a scrivere; dopo poco, ti rendi conto che un paio di titoletti farebbero comodo al tuo lettore. Allora inizi a scrivere dei titoli in maiuscolo, poi stacchi due righe, e inizi a scrivere.
A questo punto, vuoi separare dei paragrafi, quindi lasci delle righe vuote tra i blocchi di testo per migliorare la leggibilità.
Poi usi dei semplici trattini per gli elenchi puntati, dei numerini per gli elenchi numerati.

Il risultato finale è sempre e comunque un testo semplice, ma il tuo lettore è perfettamente in grado di immaginarselo formattato, come se lo avessi scritto in Word.

Se sei una persona creativa (e hai molto tempo a disposizione), potresti persino esserti sbizzarrito creando veri e propri elementi grafici di layout, realizzati sempre e solo con caratteri ASCII, e con risultati anche apprezzabili. Ad esempio:

WYSIWYG vs WYMIWYG

Che? Cosa diavolo c'è scritto qui sopra?
I due acronimi nel titolo stanno per:

• What You See Is What You Get (ottieni ciò che vedi): significa che l'editor che stai usando ti presenta il documento formattato, esattamente nella sua versione finale, pronta per la stampa o l'esportazione
• What You Mean Is What You Get (ottieni ciò che intendi): significa che, proprio come in un "linguaggio di programmazione", in questo caso di markup, il testo scritto include informazioni sulla formattazione finale del documento, inserite manualmente dall'autore

Questi due approcci sono diametralmente opposti dal punto di vista dell'autore, eppure, sbirciando sotto al cofano, osserviamo che non sono poi così diversi.

Infatti, qualsiasi editor di testo complesso ci sta nascondendo un linguaggio di markup che esso stesso utilizza per descrivere la formattazione che ci viene presentata. Questo linguaggio di markup potrebbe in effetti non essere human readable, proprio perché non è pensato per essere ispezionato o modificato direttamente dall'utente.

D'altra parte, anche l'approccio opposto necessita di strumenti appositi che "compilino" il nostro markup sorgente in un formato di presentazione (HTML, PDF, DOCX, ODT, ecc).

Tra questi due approcci, è evidente che il programmatore medio preferisca il secondo: sorgenti, compilazione, ottieni ciò che intendi, sono chiaramente concetti affini a chi di mestiere scrive codice. Non a caso, generalmente un programmatore progetterà una pagina web in HTML, e non disegnandola in un editor che poi esporta ad HTML. Il senso stesso del codice sta nell'avere controllo su ciò che si sta dichiarando di indentere (What One Means), perché al di là di quello che sarà il risultato finale, altri programmatori dovranno tornare a modificare quella pagina e vorranno capire cosa l'autore precedente aveva in mente (What One Meant) quando l'ha realizzata.

Quindi, veniamo a noi e scopriamo insieme perché Markdown è un linguaggio di markup così interessante.

Che cos'è Markdown?

Markdown è un linguaggio di markup minimale, finalizzato alla produzione di testo formattato o Rich Text e modificabile con qualsiasi editor di testo semplice.

La peculiarità di Markdown consiste nel fatto che i segni della formattazione, cioè ciò che l'autore intende sono pensati per rendere il testo comodamente leggibile a monte della conversione in HTML, PDF o altri formati analoghi.

In altre parole, Markdown non è altro che una convenzione su tutti quei simbolismi e spaziature che tutti noi adottiamo quando scriviamo documenti strutturati in testo semplice. Standardizzando questa convenzione è possibile stabilire delle regole di conversione da Markdown ad altri formati di testo, senza però rinunciare alla leggibilità del testo originale.

Vediamo come usare questo linguaggio.

Come si usa Markdown?

Per iniziare a scrivere un documento Markdown dobbiamo semplicemente creare un file con estensione .md. A questo punto potremo aprirlo con qualsiasi editor di testo semplice, ma averne uno che conosce la sintassi ci sarà di molto aiuto, perché ci mostrerà contemporaneamente quello che noi abbiamo scritto e quello che il lettore vedrà.

Vediamone alcuni:

Editor Markdown

Sintassi Markdown

Una volta aperto il nostro editor, iniziamo a scrivere. Per usare bene Markdown, torna utile (ma non è necessario) conoscere un minimo di HTML, perché tutte le sintassi corrispondono a dei tag ben precisi.

Titoli

Le intestazioni che in HTML corrispondono ai tag h1-h6, in Markdown si rendono con il prefisso # prima del testo del titolo.

In alternativa, i primi due livelli possono essere scritti così:

Qualsiasi sottolineatura può essere formata da un minimo di 3 caratteri = o -, fino a un massimo arbitrario, quindi è possibile sottolineare l'intero titolo.

Righe e paragrafi

L'interruzione di riga (HTML: <br>) si ottiene mettendo due spazi al termine della riga. I paragrafi (<p>) si ottengono con una riga vuota tra due blocchi di testo.

Decorazioni al testo

L'enfasi (che in HTML è resa con <em> e non con <i>) e il grassetto (HTML <strong> e non <b>) vengono resi rispettivamente con una e due occorrenze di uno dei due caratteri * e _.

Personalmente ho adottato la convenzione che vuole _ per il corsivo e ** per il grassetto. Fosse stato per me, sarebbe bastato distinguere per carattere e non per numero di occorrenze, che può rivelarsi scomodo. Ad ogni modo le due cose possono essere usate insieme:

Elenchi

Gli elenchi puntati (<ul>) si rendono come segue:

L'importante è non mischiare i simboli utilizzati per rappresentare i pallini, altrimenti Markdown spezzerà l'elenco.

Quelli numerati (<ol>) invece:

Suggerimento: usando sempre 1. per rappresentare il numero, è più facile cambiare l'ordine dei punti nell'elenco.

Gli elenchi possono essere annidati tabbando (o spaziando di almeno due spazi, qualche editor ne vuole quattro).

Codice

Una parola chiave o una singola riga di codice (HTML <code>) può essere resa inline usando il backtick `.

Un intero blocco (snippet) di codice, può essere reso con:

Nota: usando 4 backtick anziché 3, è possibile usare i tre backtick anche dentro al blocco di codice. Usando 2 backtick anziché 1, è possibile usare il backtick singolo in una parola chiave inline.

Ehi tu, guarda che io ho studiato psicologia neuro-linguistica comportamentale, e so cosa stai pensando: e come %&/%$ lo scrivo il backtick con la tastiera italiana?

Non panicare, ecco un po' di modi:

1. In Windows, tieni premuto Alt e digita 96 nel tastierino numerico.
2. Cambia temporaneamente tastiera (Ctrl + Start + Spazio) se hai quella inglese, poi premi quello che in italiano è il tasto \. Io personalmente faccio così
3. Cerca su Google backtick, poi copia-incollalo.
4. Usa un editor markdown che aggiunge la sintassi di formattazione con un'apposita toolbar.

Link e immagini

Link e immagini si rendono in modo molto simile:

Citazioni

Una citazione (HTML <blockquote>) si rende mettendo > all'inizio di ogni riga della stessa.

Righe orizzontali

A volte è utile semplicemente spezzare il testo. Per ottenere un separatore orizzontale (HTML: <hr>), si può usare *** oppure — oppure ___. Personalmente uso sempre —, ma l'idea di Markdown è che anche il "sorgente" dev'essere leggibile quindi vi offre sempre qualche alternativa per rendere graficamente ciò che volete ottenere.
Per lo stesso motivo, 3 è semplicemente la lunghezza minima da scrivere, ma potete ottenere un separatore scrivendo una riga lunga quanto volete.

Attenzione: spaziate una riga orizzontale con una riga vuota sopra e una riga vuota sotto, rischiate di volere (Mean) una riga e ottenere (Get) un titolo secondario.
Invero, in Markdown sarebbe sempre meglio spaziare elementi di tipo diverso come titoli, paragrafi e elenchi, a meno che non siano decorazioni del testo.

Indovinate un po' come ho fatto questa riga qui sopra!

Fragranze di Markdown

Benissimo, abbiamo un bel po' di formattazione. E se volessi includere tabelle, grafici, formule matematiche?
Qui casca l'asino, ma neanche troppo.

A tutti gli effetti Markdown non è un linguaggio, ma una famiglia di dialetti (detti flavours, cioè aromi, fragranze, un po' come se fossero i gusti del gelato) nati tutti dalla stessa esigenza. Le regole fin qui descritte sono valide per tutti questi dialetti, perché sono state standardizzate in un linguaggio comune chiamato CommonMark. Quando stai scrivendo in Markdown, avrai sempre a disposizione tutte le sintassi CommonMark, più alcune estensioni che potranno variare in base all'editor o al tool di esportazione che stai usando.

Ad esempio, io che scrivo i miei articoli in Markdown, precedentemente in questo articolo ho usato una tabella (e sto per usarne un'altra), usando una sintassi che viene da un dialetto chiamato GitHub Flavoured Markdown (GFM) ed è supportata ormai da quasi tutti gli editor.

Di fatto possiamo dire che esiste un dialetto per ogni parser; esistono parser scritti in praticamente ogni linguaggio di programmazione, quindi è praticamente impossibile non trovarne uno, qualunque sia l'ambiente in cui si sta lavorando.

Di seguito tre dialetti molto diffusi che presentano una specifica ben documentata.

Consigli utili

Benissimo, abbiamo capito che:

• Markdown è una figata
• Esistono diversi dialetti di markdown
• Sono disponibili molti editor

Come ci muoviamo concretamente per non avere problemi?

Molto semplicemente, scegliendo un buon editor come quelli suggeriti sopra, e verificando quali funzionalità mette a nostra disposizione (Typora supporta pienamente GFM). Se abbiamo bisogno di creare una documentazione veramente ricca di funzionalità avanzate come equazioni matematiche, diagrammi di flusso o altro, possiamo semplicemente adottare un editor molto completo, oppure uno che supporti estensioni.

Fermi tutti, c'è ancora una cosa di cui dobbiamo parlare.

Stili e temi in Markdown

Se non vi è sorta spontanea la domanda, è perché siete gli utenti giusti per Markdown. In ogni caso, prima o poi vi dovrete porre il problema: alla fine, il mio documento esportato, come lo stilizzo? Abbiamo detto che un sorgente .md "diventa" HTML, ma non abbiamo menzionato il CSS!

A tutti gli effetti, una volta esportato l'HTML, possiamo applicare tutti gli stili che vogliamo nel file finale, ma la maggior parte degli editor supporta l'uso diretto dell'HTML nel file .md, quindi nulla ci vieta di inserire un tag <style> e inserire lì quello che ci interessa, sapendo in anticipo come la sintassi Markdown verrà convertita nei vari tag, e stilizzando quei tag.

In aggiunta, ogni editor applica un suo foglio di stili nel momento in cui esporta, e quegli stessi stili li possiamo già vedere nell'anteprima del nostro documento. Ogni editor consente, attraverso le proprie impostazioni, di applicare temi diversi da quello predefinito, eventualmente realizzati o modificati da noi.

Con un uso sapiente di temi ed estensioni, è possibile:

• Numerare i titoli
• Creare sommari
• Aggiungere copertine, intestazioni e piè di pagina

Essendo di fatto uno strumento tecnico, con tutte le complicazioni del caso, ad essere onesti bisogna ammettere che Markdown non è esattamente per tutti.

Ma se oscilli spesso tra Notepad e altri editor, se impazzisci quando non riesci a far fare al tuo editor quello che hai in mente, se scrivi spesso documentazione tecnica, dovresti sicuramente prenderlo in considerazione, perché si tratta di uno strumento versatile e potente, le cui sintassi base possono essere tranquillamente apprese nell'arco di pochi minuti.

Tutto il resto può tranquillamente restare inesplorato, fino al momento in cui ne avrai bisogno, e per allora saprai certamente come ottenere e usare tutte le estensioni che ti servono.