Markdown è un linguaggio di marcatura creato da John Gruber nel 2004, pensato per poter scrivere dei testi marcati con una sintassi semplice e pulita, in modo che potessero essere facilmente letti anche senza formattazione^[1].

Questa sua caratteristica lo rende un ottimo strumento per prendere appunti in maniera veloce, preoccupandosi in un secondo momento della loro resa grafica.

Perché usare Markdown?

Normalmente per cambiare lo stile del testo in un classico editor che supporta la formattazione, selezioniamo la porzione di testo che ci interessa e premiamo un bottone per applicare stili quali il grassetto, il corsivo o il sottolineato, cambiare dimensione del testo, inserire immagini.

Produrre un testo con Markdown significa invece scrivere in un semplice file di testo, con qualsiasi editor testuale (anche Blocco Note), e aggiungere delle marcature che descrivono la formattazione desiderata. Molti editor di testo sono compatibili con Markdown e sono in grado di mostrare la formattazione finale in tempo reale.

Anche se l'editor non dovesse essere compatibile, Markdown è pensato per poter essere comprensibile anche senza essere processato:

L'obiettivo principale nella progettazione di Markdown è quello di rendere la sua sintassi il più leggibile possibile. L'idea è che un documento formattato con Markdown dovrebbe poter essere pubblicato così com'è, come testo semplice, senza che si noti che è stato marcato con tag o istruzioni di formattazione.

— John Gruber su https://daringfireball.net/projects/markdown/

Ci sono diversi vantaggi nell'utilizzare Markdown anziché un editor classico:

• Markdown può essere usato per qualunque cosa. Viene utilizzato per creare siti web, documenti, note, libri, presentazioni, email e documentazione tecnica.
• Markdown è portatile. I file che contengono del testo formattato con Markdown possono essere aperti praticamente con qualunque applicazione. Se si cambia idea sull'editor Markdown che si sta utilizzando, è sufficiente aprire il file su un altro editor. Questo è in netto contrasto con quanto avviene con applicazione come Microsoft Word, il quale vincola il contenuto all'interno di un formato proprietario.
• Markdown è agnostico rispetto alla piattaforma. È possibile creare file Markdown in qualsiasi dispositivo, con qualsiasi Sistema Operativo.
• Markdown è resiliente al futuro. Anche se l'applicazione che usiamo dovesse a un certo punto smettere di funzionare, saremmo comunque in grado di leggere ciò che abbiamo scritto fino a quel momento utilizzando un editor di testo qualsiasi. È una considerazione importante per quanto riguarda libri, tesi universitarie e altri documenti che devono essere conservati per un tempo indefinito.
• Markdown è ovunque. Siti web come Reddit, GitHub, GitLab e tanti altri supportano Markdown, così come anche tante applicazioni desktop e web.

Funzionalità di base

Il linguaggio supporta una serie esaustiva di blocchi semantici, che consente a diversi software non solo di visualizzarne una versione formattata, ma anche di convertire i documenti scritti in Markdown in HTML, PDF e altri formati con una certa facilità.

Di seguito le marcature supportate:

• intestazioni (con grandezze da una scala da 1 a 6)
• paragrafi
• liste (ordinate e non ordinate, e indentate)
• corsivo
• grassetto
• sottolineato
• barrato
• tabelle
• note a piè di pagina
• citazioni
• callout
• link
• immagini
• blocchi di codice
• codice in linea

Intestazioni

Le intestazioni sono i titoli presenti nel documento. Esistono sei livelli di intestazioni, che corrispondono ai tag HTML <h1>, <h2>, ..., <h6>, dal più importante al meno importante (gerarchicamente).

Buone pratiche

Lascia uno spazio tra il carattere speciale e il testo

È bene lasciare uno spazio tra il carattere # (cancelletto) e il titolo dell'intestazione.

Lascia una riga vuota prima e dopo le intestazioni

È opportuno inoltre lasciare uno spazio prima e dopo ogni intestazione.

Infine, sia in Markdown che in HTML, è meglio non annidare intestazioni più importanti all'interno di intestazioni di rango più basso, in modo da rispettarne il significato semantico e agevolare il funzionamento degli strumenti che interpretano il linguaggio. Alcuni di essi, come Obsidian, consentono per esempio di collassare ciò che è presente all'interno di un blocco appartenente a una certa intestazione. Il contenuto da includere nel blocco viene dedotto dalle intestazioni: inizia da un'intestazione di un certo livello e si interrompe all'intestazione dello stesso livello successiva.

Esempio:

# Titolo principale

Paragrafo introduttivo

## Titolo di secondo livello

Paragrafo del secondo livello

### Titolo di terzo livello

Paragrafo di terzo livello

### Titolo di terzo livello

Paragrafo di terzo livello

## Titolo di secondo livello

etc.

Fin da questo semplice esempio è possibile apprezzare la chiarezza di Markdown e la sua facilità di lettura ancor prima di applicare la formattazione.

Il documento inizia con un'intestazione di primo livello (equivalente a <h1>). Tipicamente questa rappresenta il titolo, e ne avremo solo una in tutto il documento.

Nei sistemi predisposti nativamente, o basati su, Markdown, come Obsidian o gli editor di testo di GitHub e GitLab, questa intestazione è solitamente assegnata al nome del file, ed è quindi consigliabile che il testo effettivo abbia una o più intestazioni di secondo livello come rango più alto.

Troviamo poi un'intestazione di secondo livello (<h2>) che contiene al suo interno due intestazioni di terzo livello (<h3>).

La prima intestazione di secondo livello termina semanticamente quando inizia la successiva (e ultima, in questo esempio).

Quanto scritto nell'esempio verrà reso graficamente in un modo simile al seguente:

Naturalmente, lo stile esatto applicato dipenderà dal software che interpreta il contenuto. Potendo convertire il testo in HTML (ciò che vedete a schermo in questo momento ha subito questo processo), è possibile scrivere del codice CSS per modificare lo stile finale.

Paragrafi

Il paragrafo è semanticamente il blocco di testo più semplice contenuto in un documento. Ad esso verrà applicato solo lo stile di base del testo, più eventualmente dei margini verticali per accentuarne la separazione da altri blocchi (al netto di altri stili scritti ad hoc). In Markdown, ogni sequenza di caratteri non accompagnati da simboli speciali (es. cancelletto, asterisco, lineetta) rappresenta un paragrafo.

È possibile terminare un paragrafo e iniziarne un altro con due andate a capo, ovvero lasciando una riga vuota tra due blocchi di testo.

Si consiglia di non usare indentazioni per i paragrafi.

Interruzioni di riga

Per interrompere una riga è possibile terminarla con due o più spazi, e poi andare a capo.

Corsivo

Per scrivere in corsivo una o più parole, è possibile usare il carattere * (asterisco) o _ (underscore) per circoscrivere la porzione di testo che si intende scrivere in corsivo.

Buone pratiche

Usa gli asterischi all'interno delle parole

Dato che non tutte le applicazioni Markdown sono d'accordo su come gestire gli underscore all'interno di una parola, per scrivere in corsivo solo parte di una parola si consiglia di usare l'asterisco:

Grassetto

Per scrivere in grassetto una o più parole, è possibile usare due caratteri ** (asterisco) o __ (underscore) per circoscrivere la porzione di testo che si intende scrivere in grassetto.

Buone pratiche

Usa gli asterischi all'interno delle parole

Dato che non tutte le applicazioni Markdown sono d'accordo su come gestire gli underscore all'interno di una parola, per scrivere in grassetto solo parte di una parola si consiglia di usare l'asterisco:

Combinare grassetto e corsivo

È possibile ottenere un testo grassetto e corsivo con una qualsiasi di queste combinazioni:

• Tre asterischi
• Tre underscore
• Un asterisco e due underscore
• Un underscore e due asterisci

Buone pratiche

Usa gli asterischi all'interno delle parole

Anche in questo caso si consiglia di utilizzare gli asterischi per enfatizzare parti di testo contenute all'interno di una parola.

Citazioni

Per scrivere un blocco citazione si utilizza il carattere > (maggiore) all'inizio di ogni riga della citazione.

Esempio:

> Signori si nasce, e io lo nacqui, modestamente.
>
> — Totò in *Signori si nasce*

Questo blocco di codice verrà mostrato in questo modo:

Signori si nasce, e io lo nacqui, modestamente.

— Totò in Signori si nasce

È possibile anche annidare blocchi di citazione e inserirvi all'interno altri blocchi Markdown:

> #### Qua inizia il blocco!
>
> - Primo elemento di una lista
> - Secondo elemento di una lista
>
>>  **Questa** è una *citazione* annidata.
>
> Fine del blocco

Risultato:

Qua inizia il blocco!

• Primo elemento di una lista
• Secondo elemento di una lista

Questa è una citazione annidata.

Fine del blocco

Liste ordinate

È possibile creare una lista ordinata anteponendo un numero intero puntato all'elemento della lista. Ogni elemento della lista deve essere separato dal precedente con un'andata a capo. In questo genere di lista è indifferente il numero che viene inserito, perché la lista verrà sempre visualizzata con numeri che vanno da 1 a n, dove n è il numero di elemento nella lista. Il primo elemento dovrà tuttavia iniziare con il numero 1.

Per annidare gli elementi, è necessario iniziare indentare le righe corrispondenti.

Liste non ordinate

È possibile scrivere liste non ordinate in maniera analoga a quelle ordinate, ma utilizzando i caratteri - (meno), * (asterisco) e + (più) all'inizio di ogni elemento.

Buone pratiche e consigli

Usa lo stesso carattere per tutti gli elementi

Per compatibilità con le varie applicazioni utilizzate per leggere Markdown, è meglio non mischiare questi caratteri:

Escape dei numeri a inizio riga

È possibile scrivere un numero all'inizio di un elemento appartenente a una lista non ordinata aggiungendo con il carattere di escape \ (backslash):

Contenuto all'interno degli elementi di una lista

È possibile inserire elementi Markdown tra un elemento e il successivo di una lista scrivendoli indentati, e separati dall'elemento precedente e da quello successivo da una riga vuota. Di seguito alcuni esempi.

Inserire un paragrafo

- Questa è un elemento della lista
- Questa è un altro elemento della lista

	Questo è un paragrafo

- Questo è l'ultimo elemento della lista

• Questa è un elemento della lista

• Questa è un altro elemento della lista

  Questo è un paragrafo

• Questo è l'ultimo elemento della lista

Inserire una citazione

- Questa è un elemento della lista
- Questa è un altro elemento della lista

	> Questo è una citazione

- Questo è l'ultimo elemento della lista

1. Questa è un elemento della lista

2. Questa è un altro elemento della lista

   Questa è una citazione

3. Questo è l'ultimo elemento della lista

Inserire una lista

È possibile inserire liste ordinate all'interno di liste non ordinate e vice versa, sia come contenuto intermedio di un elemento, sia come elemento della lista stessa

- Questa è un elemento della lista
- Questa è un altro elemento della lista

	1. Elemento intermedio
	2. Elemento intermedio

- Questo è l'ultimo elemento della lista
	1. Elemento indentato della lista
	2. Elemento indentato della lista

• Questa è un elemento della lista

• Questa è un altro elemento della lista

  1. Elemento intermedio
  2. Elemento intermedio

• Questo è l'ultimo elemento della lista

  1. Elemento indentato della lista
  2. Elemento indentato della lista

Codice

In Markdown è possibile inserire dei blocchi di codice attraverso l'uso del carattere ` (backtick).

Codice in linea

Per scrivere del codice all'interno di una riga di testo semplice si utilizzerà un backtick di apertura e un backtick di chiusura:

Per elencare tutti i file contenuti in una *directory* su *Linux*, usare il comando `ls -la`.

Verrà visualizzato in questo modo:

Per elencare tutti i file contenuti in una directory su Linux, usare il comando ls -la.

Oppure:

Per enfatizzare del testo in *HTML* è possibile usare questa sintassi: `<strong>testo in grassetto</strong>`.

E il risultato sarà:

Per enfatizzare del testo in HTML è possibile usare questa sintassi: <strong>testo in grassetto</strong>.

In quest'ultimo esempio è possibile notare come anche il codice HTML non venga renderizzato come tale, quando inserito all'interno di due backtick.

Blocco di codice

Per dedicare un intero blocco alla scrittura di codice, si inizierà e terminerà il suddetto blocco con tre backtick. Opzionalmente è possibile scrivere accanto ai backtick di apertura il nome del linguaggio che andremo a scrivere. In questo modo, i software potranno evidenziare correttamente la sintassi del codice (syntax highlighting), qualora supportassero questa funzione:

Verrà visualizzato in questo modo:

<article>
	<h1>Titolo dell'articolo</h1>
	<div>Testo dell'articolo</div>
</article>

Escape del carattere backtick

Per scrivere il carattere backtick all'interno di un testo già delimitato da backtick, è necessario usare dei doppi backtick:

Per interrompere una riga è possibile terminarla con due o più spazi, e poi andare a capo.

Linee orizzontali

Markdown prevede la possibilità di tracciare delle linee di divisione del documento, utilizzando le seguenti sequenze di caratteri: --- (trattino), ___ (underscore) e *** (asterisco).

Il risultato è il seguente:

Buone pratiche

Lasciare uno spazio prima e dopo la linea

Link

Per scrivere dei collegamenti ipertestuali in Markdown si utilizza questa sintassi:

[Nome visualizzato](collegamento al sito "Tooltip opzionale")

Es.

Clicca [qui](https://google.it "Questo è un motore di ricerca") per andare su Google.

Viene mostrato in questo modo:

Clicca qui per andare su Google.

Molti software riconoscono automaticamente i link. Per forzare la visualizzazione di una parte di testo come collegamento ipertestuale, è necessario racchiuderlo tra parentesi angolari. Questo funziona anche con gli indirizzi e-mail:

<https://google.it>
<prova@example.com>

Verranno visualizzati in questo modo:

https://google.it
prova@example.com

Immagini

Si possono inserire delle immagini nel testo con questa sintassi, simile a quella dei link, ma con un ! (punto esclamativo) anteposto alle parentesi quadre:

![Pattini a rotelle](https://upload.wikimedia.org/wikipedia/commons/thumb/a/a3/Impala_Marawa_Quad_Skates_Comparison.jpg/1599px-Impala_Marawa_Quad_Skates_Comparison.jpg?20221021034009 "Questi sono pattini a rotelle")

Escape dei caratteri

Alcuni caratteri, come abbiamo visto, hanno un significato particolare in Markdown. Per visualizzare questi caratteri come testo semplice è necessario effettuare un escape, ovvero inserire uno o più caratteri che comunicano all'interprete Markdown che uno specifico carattere non ha un significato particolare. Solitamente si antepone un singolo carattere a quello di cui vogliamo fare l'escape.

Nel caso del Markdown, così come in molti altri contesti, il carattere in questione è il backslash \.

\* Senza backslash, il carattere asterisco farebbe diventare questa riga l'elemento di una lista

I caratteri di cui si può fare l'escape sono i seguenti:

HTML

Molte aplicazioni per scrivere Markdown consentono di inserire del codice HTML direttamente nel testo, mentre altre non lo consentono per ragioni di sicurezza.

Nel caso in cui questo fosse possibile, sarà sufficiente scrivere il codice perchè questo venga rappresentato graficamente.

es.

<div style="display: flex; height: 100px; width: 100%; justify-content: center; align-items: center;">
	<div style="display: flex; height: 24px; justify-content: center; align-items: center; background-color: #ac0202; color: white; padding: 8px 8px 8px 8px; border-radius: 8px;">
		Questo è un contenuto HTML! Qui il _Markdown_ non funziona!
	</div>
</div>

diventa

Non ci sono regole per la formattazione e il contenuto, ma come linee guida generali è possibile seguire questi punti:

• Separare con una riga vuota i tag con proprietà display: block (es. <div>, <table>, <pre>, <p>, etc.)
• Se possibile, non indentare i tag con tab o spazi