Cos’è Markdown e come si usa

Se sei un creatore di contenuti e non hai vissuto in una caverna negli ultimi quindici anni dovresti conoscere il linguaggio Markdown. Ma soprattutto dovresti sapere come usarlo al meglio.

Se non lo sai, sei nel posto giusto.

Cos’è Markdown

Markdown è un linguaggio di marcatura (markup) creato nel 2004 da John Gruber e Aaron Swartz.

Perché creare un altro linguaggio di marcatura, se esistevano già HTML, LaTeX e tanti altri?

Markdown si basa su 3 principi:

1. immediatezza
2. compatibilità
3. longevità

Immediatezza di Markdown

Gruber e Swartz avevano come obiettivo permettere la creazione di contenuti formattati anche agli utenti meno esperti, senza abilità di web design o di formattazione.

Per creare contenuti formattati in HTML un utente deve usare una certa sintassi e una serie di oltre 100 elementi (detti tag).

Al contrario, la formattazione del testo in Markdown è molto più immediata. Un testo in Markdown è un file di testo semplice (plain text), in cui non cambiano le dimensioni dei carattere, il colore o il font, come avviene ad esempio in Microsoft Word.

La sintassi è più semplice, senza tag, e con pochi simboli che servono a contrassegnare la funzione del testo.

La sintassi di base s’impara in dieci minuti.

Ad esempio, per scrivere un testo in grassetto in HTML, è necessario scrivere ben 17 caratteri, quelli corrispondenti al tag strong: il tag di apertura va racchiuso fra parentesi angolari (<…>), così come quello di chiusura, che inoltre porta l’indicatore della barra inclinata per segnalare che è appunto un tag di chiusura (</…>).

<strong>Testo in grassetto</strong>

In Markdown invece i caratteri necessari sono solo 4, una coppia di due asterischi:

**Testo in grassetto**

In alcuni casi non è necessario inserire alcun simbolo.

Mentre in HTML un paragrafo va indicato con la coppia di tag <p>…</p>, in Markdown basta inserire una riga vuota fra i paragrafi.

Con questi e altri semplici accorgimenti, Markdown semplifica enormemente la creazione di documenti formattati.

Senza contare che in un file Markdown è sempre possibile aggiungere parti di codice HTML, che saranno elaborate da Markdown come tali.

Compatibilità di Markdown

Markdown ha un’altra grande virtù: i file *.md o *.markdown si possono convertire in HTML e in molti altri formati usando un Markdown processor, un apposito programma.

Un altro vantaggio è dato dal fatto che – essendo i file *.md file di testo semplice, cioè apribili con qualsiasi elaboratore di testi – non dipendono da un particolare software o applicazione.

A differenza dei file di testo creati dagli elaboratori di testo proprietari, i file di testo scritti in Markdown possono essere condivisi tra dispositivi e sistemi diversi.

Longevità di Markdown

Dato che i file scritti in Markdown non sono compilati, ma sono file di testo semplice, è ragionevole supporre che saranno leggibili dagli elaboratori per moltissimi anni.

Anche se un domani cessassero di esistere tutti i programmi che usano Markdown (cosa alquanto improbabile, data la sua diffusione) un utente potrà sempre accedere al contenuto di questi file con un qualsiasi editor di testo (come il blocco note di Windows, per capirci).

Per cosa si usa Markdown

Alla luce di quanto esposto, non è un caso dunque che Markdown stia diventando lo standard di scrittura per accademici, ricercatori, content writer e blogger.

Alcuni siti come GitHub, Reddit, Stack Exchange, OpenStreetMap o SourceForge hanno adottato la sintassi Markdown per i commenti degli utenti.

Markdown si può usare in qualunque situazione in cui sia necessario scrivere testo formattato.

Spesso si usa per formattare i file README nei progetti di sviluppo software, per scrivere i messaggi nei forum di discussione, per scrivere documentazione tecnica, per creare articoli e pagine all’interno di strumenti per la creazione di siti web, come Grav, il CMS con cui è stato creato il sito di Qabiria su cui ti trovi.

Molti programmi per la creazione di note e knowledge base usano Markdown come loro formato standard, ad esempio Obsidian.

Le varianti di Markdown

Può sorprendere, ma non esiste uno standard definito per Markdown, ad eccezione dell’articolo originale di John Gruber, che tuttavia descrive il linguaggio lasciando aperto lo spazio ad ambiguità e interpretazioni.

La documentazione ufficiale sulla sintassi non affronta o affronta in modo vago alcune questioni, come le sottoliste, la regola dei “quattro spazi” e altro.

Di conseguenza, sono nate diverse varianti del linguaggio originale che ne correggono incongruenze o errori, oppure che aggiungono funzioni non previste inizialmente.

Uno degli sforzi di standardizzazione più coerenti è quello chiamato Commonmark che t’invito a conoscere.

Se si vogliono confrontare le varianti, si può ricorrere a Babelmark che analizza l’output delle varie implementazioni evidenziandone le differenze.

Oltre alle varianti propriamente dette, sono nate anche una serie di estensioni, cioè altri linguaggi che aggiungono nuove caratteristiche a Markdown, come tabelle, note a piè pagina, liste di definizioni, ecc.

Alcuni di questi linguaggi “estesi” sono:

• Markdown Extra
• GitHub Flavored Markdown (GFM)
• MultiMarkdown
• Maruku
• Kramdown
• Pandoc’s Markdown

Che programma usare per scrivere in Markdown

Come dovrebbe essere chiaro a questo punto, per scrivere in Markdown basta un qualsiasi elaboratore di testo semplice.

Tuttavia, esistono editor specifici per tutti i maggiori sistemi operativi. Questi editor di solito permettono di visualizzare anche un’anteprima del testo formattato con gli stili applicati, cioè una versione renderizzata come HTML di quello che si sta scrivendo.

Chi usa emacs, gedit, vim, BBEdit, NotePad++ può usare plugin specifici o addirittura funzioni integrate per evidenziare la sintassi dei file Markdown e vedere la loro anteprima.

In Notepad++ si può usare il plugin MarkdownViewer++ per avere una schermata di anteprima e poter esportare il contenuto in HTML o PDF.

Un ottimo programma online per impratichirsi con Markdown senza dover installare nulla è Dillinger, un editor Markdown online abilitato per il cloud, basato su HTML5. Anche Dillinger consente di esportare i file creati in Markdown, HTML e PDF.

Sintassi di base di Markdown

Vediamo ora le regole di base per formattare testi in Markdown.

Corsivo e grassetto

Per contrassegnare un testo come corsivo basta aggiungere un trattino basso (underscore) o un asterisco prima e dopo il testo, senza lasciare spazi fra il trattino (o l’asterisco) e la parola, in questo modo:

_testo in corsivo_

*testo in corsivo*

In modo simile, per evidenziare una parola o una frase in grassetto bisogna racchiuderla fra 2 asterischi o trattini bassi, così:

**testo in grassetto**
__testo in grassetto__

Testo barrato

Per barrare un testo, bisogna racchiuderlo fra due coppie di tildi ~~ (in Windows si scrive digitando ALT + 126 sul tastierino numerico).

~~testo barrato~~

Titoli o intestazioni

I titoli si possono formattare in due modi:

• inserendo nella riga sottostante il testo dei segni di “uguale” = o dei trattini, oppure
• precedendo il testo con uno o più simboli di “cancelletto” #, usandone uno per i titoli di primo livello e più d’uno per i titoli di livello inferiore. Non è necessario “chiudere” il testo con un altro segno di cancelletto, ma se lo si fa per ragioni estetiche, Markdown non se ne lamenta.

Questo è un esempio del primo modo (chiamato Setext):

Questo è un titolo che verrà convertito in H1
=============================================

Questo è un titolo che verrà convertito in H2
---------------------------------------------

Mentre questo è un esempio del secondo modo (chiamato atx):

# Questo è un titolo H1
## Questo è un titolo H2
...
##### Questo è un titolo H5

Paragrafo

In Markdown un paragrafo è costituito da una o più righe di testo consecutive separate da una o più righe vuote. Questo paragrafo sarà separato dal resto da un hard return. Se si vuole inserire un soft return, cioè un a capo indicato con il tag <br /> dell’HTML, allora basta inserire due o più spazi alla fine di una riga prima di andare a capo.

Citazioni

Per evidenziare un testo come citazione, si usa il simbolo di maggiore a inizio capoverso. È possibile anche nidificare citazioni una dentro l’altra usando più simboli e anche usare altra sintassi Markdown all’interno della citazione, come indicato in questo esempio:

> Questa è una citazione di primo livello.
> > Questa è una citazione di secondo livello.
>
> Qui si usa un **grassetto**
> 
> ## E questo è un titolo dentro una citazione.

Lo stile con cui saranno visualizzate le citazioni dipende dal dispositivo e dal CSS associato al file HTML prodotto.

Elenchi puntati e numerati

Per creare un elenco puntato basta aggiungere un asterisco, un simbolo di più o un trattino all’inizio della riga, seguito da uno spazio e dall’elemento della lista.

Per creare un elenco numerato invece si fa precedere il testo da una cifra seguita da un punto, uno spazio e quindi il testo.

L’ordine scelto per l’elenco numerato è indifferente e non influisce sul risultato. Si può scrivere cioè 1. prima voce o 7. prima voce. Il numero che comparirà nella pagina generata da Markdown dipenderà dall’effettiva posizione di quella voce all’interno della lista e dal primo numero usato.

Ecco un esempio:

* Prima voce di un elenco puntato
* Seconda voce di un elenco puntato
* Terza voce di un elenco puntato

4. Prima voce di un elenco numerato
1. Seconda voce di un elenco numerato
2. Terza voce di un elenco numerato

L’elenco numerato apparirà così:

4. Prima voce di un elenco numerato
5. Seconda voce di un elenco numerato
6. Terza voce di un elenco numerato

Codice di programmazione

Per inserire un frammento di codice in un documento Markdown in modo che venga visualizzato come <pre><code>...</code></pre> bisogna inserire quattro spazi all’inizio del capoverso.

Un altro metodo è quello di usare tre accenti gravi (backtick) ` o tre tildi ~ in una riga a sé stante per contrassegnare l’inizio del codice e altri tre su un’altra riga per contrassegnare la fine. Ad esempio:

```
print('Hello, world!')
```

Link

Per inserire collegamenti si usa una sintassi particolare: il testo da linkare va tra parentesi quadre e l’URL va subito dopo (senza spazio di separazione) fra parentesi tonde, eventualmente seguito dal nome del collegamento (che diventerà il valore dell’attributo title nell’HTML risultante), in questo modo:

Ecco un esempio di [collegamento](https://collegamento.com "Nome del collegamento")

Immagini

La sintassi delle immagini è simile a quella dei collegamenti, ma la coppia di parentesi quadre e tonde si fa precedere da un punto esclamativo, in questo modo:

![Descrizione dell’immagine](/percorso/dell/immagine/img.jpg)

Nel caso delle immagini il testo fra parentesi quadre verrà visualizzato come il valore dell’attributo alt del tag img.

Linee orizzontali di separazione

Per inserire una linea orizzontale, corrispondente al tag <hr /> dell’HTML, bisogna inserire tre o più trattini, asterischi o trattini bassi su una riga da soli, anche separati da spazi.

Ad esempio, tutte le seguenti combinazioni...

* * *
---
- - -
****

generano ciascuna una riga orizzontale:

---

---

---

---

Caratteri speciali

In alcuni casi è necessario usare il carattere della barra rovesciata (backslash) \ per generare caratteri letterali che altrimenti sarebbero interpretati da Markdown come sintassi di formattazione.

Ad esempio, se si vuole racchiudere una parola fra asterischi è necessario usare la barra rovesciata prima degli asterischi, altrimenti il testo sarebbe interpretato come corsivo, in questo modo:

\*testo fra asterischi\*

che dà come risultato *testo fra asterischi* e non testo fra asterischi (in corsivo).

Lo stesso discorso vale per altri caratteri speciali, come:

• Asterisco: *
• Trattino: -
• Trattino basso (underscore): _
• Parentesi tonde: ()
• Parentesi quadre: []
• Parentesi graffe: {}
• Punto: .
• Punto esclamativo: !
• Cancelletto: #
• Accento grave (backtick): `
• Barra rovesciata (backslash): \

Si noti che per scrivere questi caratteri a sé stanti non è necessaria la barra rovesciata. Essa è necessaria soltanto quando possono essere interpretati come sintassi di formattazione.

Come tradurre file Markdown

Ma come si traduce un testo creato in Markdown?

Dato che parliamo di file di testo, il modo più semplice è quello di aprire il file *.md con un editor di testo e tradurlo manualmente all’interno dell’editor.

In questo modo, tuttavia, non si possono sfruttare tutte le risorse per la traduzione che invece avremmo a disposizione se traducessimo il file con un programma di traduzione assistita.

Tradurre file Markdown comporta 2 problemi principali:

1. dato che non esiste uno standard, il programma di traduzione o il filtro che interpreta il file da tradurre devono tener conto di tutte le varianti e delle eventuali estensioni che, fra l'altro, non sono tutte compatibili fra loro;
2. spesso i programmi che usano Markdown abbinano la sintassi Markdown a un’intestazione in formato YAML (come avviene in Jekyll o in Grav), quindi il programma o il filtro devono essere in grado di interpretare anche questa intestazione.

Traduzione di Markdown con Trados Studio

Il programma di traduzione assistita forse più diffuso, Trados Studio, dalla versione 2019 possiede un filtro per i file Markdown.

In passato era necessario creare un filtro personalizzato usando una serie di espressioni regolari.

Il filtro ha alcune opzioni, quali:

• considerare le interruzioni di riga come tag interni;
• tradurre i blocchi di codice con un ulteriore filtro;
• tradurre i blocchi di codice HTML con un ulteriore filtro.

Si consiglia di attivare quanto meno quest’ultima opzione per veder comparire nell’editor di traduzione eventuali frammenti di HTML usati nei file Markdown.

Traduzione di Markdown con Memsource

Memsource, uno dei sistemi per la gestione delle traduzioni più diffusi ha un filtro per la traduzione dei file Markdown, che quindi possono essere importati e tradotti in Memsource senza molte complicazioni.

In particolare, presenta le seguenti opzioni al momento di importare il file da tradurre:

• scegliere la variante di Markdown da considerare (Flavor)
• segmentare le unità di traduzione in corrispondenza degli a capo hard
• mantenere gli whitespace nel documento tradotto (cioè gli spazi, gli a capo, ecc.)
• considerare o meno l’intestazione YAML (da scegliere se l’intestazione presenta testi traducibili)
• importare i blocchi di codice (espone alla traduzione il codice contenuto nel file Markdown)
• escludere gli elementi di codice

È anche possibile applicare espressioni regolari per convertire un certo testo in tag, così come definire elementi del file da convertire in tag e anche sezioni da non importare.

Infine, si può definire una lista di caratteri di cui non è necessario eseguire l’escape nel file tradotto.

Traduzione di Markdown con OmegaT

Per tradurre file Markdown in OmegaT si possono seguire due strade:

1. usare il filtro per file di testo semplice
2. usare il filtro per file Markdown compreso nel plugin di Okapi

Il filtro di file di testo semplice espone tutto il contenuto del file, quindi il traduttore deve prestare particolare attenzione a non stravolgere la sintassi di formattazione, l’eventuale intestazione, l’eventuale codice HTML o altro codice presente nel testo.

Tuttavia, in questo modo ha anche la possibilità di intervenire a mano sul testo senza limiti. Questo può essere necessario quando nella versione tradotta bisogna inserire immagini o link diversi da quelli originali, oppure bisogna aggiungere campi e valori all’intestazione YAML.

Questa opzione è dunque consigliata nei casi in cui il traduttore abbia familiarità con Markdown e con la struttura del file originale.

Il filtro per file Markdown di Okapi estrae il testo traducibile dai file Markdown. Dato che le diverse varianti di Markdown non sono tutte reciprocamente compatibili, Okapi ha scelto di progettare il filtro in modo che funzioni con CommonMark, con alcune opzioni che lo rendono compatibile anche con il GitHub-flavored Markdown (GFM).

I dettagli del filtro si trovano sul Wiki di Okapi a cui si rimanda per ulteriori dettagli. Qui basti dire che è presente un parametro per includere o escludere dalla traduzione l’eventuale intestazione YAML, che è però disattivata di default. In tal senso, se si vogliono usare opzioni diverse da quelle di default è necessario usare Rainbow per creare un file con i parametri del filtro, che andrà poi caricato in OmegaT.

Che strategia scegliere per tradurre file Markdown

Il flusso di traduzione di un file Markdown dipende non solo dal sistema che si usa per tradurlo, ma anche dal programma che ha generato e dovrà interpretare i file Markdown.

Va prestata particolare attenzione ai sistemi di traduzione automatica, perché non sempre rispettano la sintassi alla lettera. Ad esempio, traducendo un contenuto scritto in Markdown con Google Translate, la traduzione potrebbe avere un numero di accenti gravi non corrispondente all’originale, rendendo così inutilizzabile il file tradotto.