Scrivere in modo sostenibile usando il testo semplice con Pandoc e Markdown/Nozioni di base di Markdown

Markdown è una convenzione per strutturare semanticamente i tuoi documenti in testo semplice. L’idea è di identificare strutture logiche nel tuo documento (titolo, sezioni, sottosezioni, note a piè di pagina, ecc.), contrassegnarle con alcuni caratteri non invadenti e quindi «compilare» il testo risultante con un interprete di composizione che formatterà il documento in modo coerente, secondo uno stile specificato. Le convenzioni di Markdown sono disponibili in diverse «varianti» progettate per l’utilizzo in determinati contesti, come blog, wiki o repository di codice. La variante di Markdown utilizzata da Pandoc è orientata all’uso accademico. Le sue convenzioni sono descritte nella pagina Markdown di Pandoc. Le sue convenzioni includono il blocco «YAML», che contiene alcuni metadati utili.

Creiamo ora un documento semplice in Markdown. Apri un editor di testo semplice di tua scelta e inizia a digitare. Dovrebbe sembrare come questo:

---
title: Plain Text Workflow
author: Dennis Tenen, Grant Wythoff
date: January 20, 2014
---

Il Markdown di Pandoc memorizza ciascuno dei valori sopra riportati e li «stampa» nella posizione appropriata del documento prodotto una volta che si è pronti per la composizione. In seguito impareremo ad aggiungere altri campi più potenti al blocco YAML. Per ora, facciamo finta di scrivere un documento che contiene tre sezioni, ciascuna suddivisa in due sottosezioni. Lascia una riga vuota dopo gli ultimi tre trattini nel blocco YAML e incolla quanto segue:

# Section 1

## Subsection 1.1
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Il prossimo paragrafo dovrebbe iniziare così. Non indentare.

## Subsection 1.2
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.

# Section 2

## Subsection 2.1

Vai avanti e inserisci anche un testo fittizio. Lo spazio vuoto è significativo in Markdown: non indentare i paragrafi. Invece, separa i paragrafi usando una riga vuota. Le righe vuote devono anche precedere le intestazioni di sezione.

È possibile utilizzare gli asterischi per aggiungere un’enfasi in grassetto o in corsivo alle parole, come segue: *italics* e **bold**. Dovremmo anche aggiungere un link e una nota a piè di pagina al nostro testo per completare i componenti di base di un documento medio. Scrivi:

Una frase che ha bisogno di una nota. [^1]

[^1]: la mia prima nota a piè di pagina! E un [link] (https://www.eff.org/).

Quando il testo del link e l’indirizzo sono gli stessi, è più veloce scrivere ‹www.eff.org› anziché [www.eff.org](www.eff.org).

Salviamo il nostro file prima di procedere ulteriormente. Crea una nuova cartella che ospiterà questo progetto. È probabile che tu abbia un sistema per organizzare i tuoi documenti, progetti, illustrazioni e bibliografie. Ma spesso il tuo documento, le sue illustrazioni e la sua bibliografia si trovano in cartelle diverse, il che rende difficile tenerne traccia. Il nostro obiettivo è creare una singola cartella per ogni progetto, con tutti i materiali pertinenti inclusi. La regola generale è un progetto, un testo, una cartella. Chiama il tuo file main.md o qualcosa del genere, dove «md» sta per markdown.

Una volta salvato il file, aggiungiamo un’illustrazione. Copia un’immagine (qualsiasi immagine piccola) nella tua cartella e aggiungi il seguente testo nel corpo del testo ![image caption](your_image.jpg). A questo punto, il tuo main.md dovrebbe apparire come il file seguente. Puoi scaricare questo file.md di esempio qui.

---
title: Plain Text Workflow
author: Dennis Tenen, Grant Wythoff
date: January 20, 2014
---

# Section 1

## Subsection 1.1
Lorem *ipsum* dolor sit amet, **consectetur** adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Subsection 1.2
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.

Il prossimo paragrafo dovrebbe iniziare così. Non indentare.

# Section 2

## Subsection 2.1
![image caption](your_image.jpg)

## Subsection 2.2
Una frase che ha bisogno di una nota.[^1]

[^1]: la mia prima nota a piè di pagina! E un [link](https://www.eff.org/)

Come faremo tra poco, questo semplice file di testo può essere trasformato in un bel PDF:

Schermata di un PDF prodotto da Pandoc

Se vuoi avere un’idea di come questo tipo di markup verrà interpretato come testo formattato in HTML, prova questa sandbox online e gioca con vari tipi di sintassi. Ricorda che alcuni elementi del Markdown in versione Pandoc (come il blocco del titolo e le note a piè di pagina) non funzioneranno in questo modulo web, che accetta solo le funzioni di base.

A questo punto, dovresti passare un po ’di tempo ad esplorare alcune delle altre funzionalità di Markdown come le citazioni (rappresentate con il simbolo›), elenchi puntati che iniziano con * o —, interruzioni di riga che iniziano con | (utile per la poesia), tabelle e alcune delle altre funzioni elencate sulla pagina del markdown di Pandoc.

Presta particolare attenzione allo spazio vuoto e al flusso dei paragrafi. La documentazione lo afferma in modo sintetico quando definisce un paragrafo come «una o più righe di testo seguite da una o più righe vuote». Nota che «gli a capo sono trattati come spazi» e che «se hai bisogno di un’interruzione di riga devi inserire due o più spazi alla fine di una riga». Il modo migliore per capire cosa significa è sperimentare liberamente. Usa la modalità di anteprima del tuo editor o esegui semplicemente Pandoc per vedere i risultati dei tuoi esperimenti.

Soprattutto, ti evita la necessità di formattare. Ricorda che stai identificando unità semantiche: sezioni, sottosezioni, enfasi, note a piè di pagina e illustrazioni. Anche *corsivo* e **grassetto** in Markdown non sono realmente segni di formattazione, ma indicano un diverso livello di enfasi. La formattazione avverrà più tardi, una volta che tu conosca la collocazione e i requisiti della pubblicazione.

Ci sono programmi che ti permettono di vedere un’anteprima dell’output di Markdown mentre modifichi il tuo file di testo normale, li indichiamo di seguito nella sezione Risorse utili. Pochi tuttavia supportano note a piè di pagina, illustrazioni e bibliografie. Per trarre il massimo vantaggio da Pandoc, si consiglia di conservare sul proprio computer i file di testo semplici salvati localmente.