Introduzione
Markdown è un linguaggio di markup con una sintassi di testo semplice progettata in modo che possa essere convertito in formato HTML e in molti altri formati.
La sintassi Markdown è stata sviluppata da John Gruber e l’ultima versione è la 1.0.1 del dicembre 2004.
I file markdown hanno estensione .md od anche .markdown (ma meno comune).
La descrizione del progetto Markdown dal sito ufficiale di John Gruber:
“A text-to-HTML formatting syntax for web writers, implemented as a plug-in for Movable Type, Blosxom, and BBEdit. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).”
Markdown è composto da due elementi principali:
- un set di regole di sintassi per formattare un file scritto in testo piano
- un software che consente di convertire il file di testo dal formato markdown ad HTML
La caratteristica principale della sintassi markdown è consentire la facilità di lettura e comprensione del file in testo piano anche senza necessariamente convertirlo in formato HTML.
Le sue caratteristiche lo rendono il formato ideale per scrivere documenti “leggeri” ma presentabili con un formattazione essenziale ed adeguata per una documentazione tecnica.
Per questo motivo è diventato ormai uno standard nel mondo degli sviluppatori in particolare nei progetti GitHub.
Markdown è indipendente dalla piattaforma, è portabile ed è universalmente diffuso.
Interpretare il formato markdown
Esistono numerosi software di interpretazione del formato markdown da installare sul proprio desktop o da utilizzare on-line.
Anche nel blocco note di Windows è stato aggiunto il supporto per l’interpretazione della sintassi MarkDown
Limitazioni visualizzazione anteprima del blocco note:
- ID titoli
- in generale sintassi con tag html (sottolineato, evidenziato, colorato, apice…)
- pannelli
- citazioni
- linea orizzontale
- porzioni codice
- note
- definizioni
- immagini
- shortcode per icone
- formule matematiche
- grafici
- abbreviazioni
- sezioni collassate
Sicuramente lo strumento più comodo e più completo da utilizzare per gli sviluppatori di software è VS Code e le sue estensioni (per una guida all’utilizzo di VS Code vedi l’articolo Sviluppare su IBM i con VS Code). VS Code ha già integrato di base un visualizzatore di file markdown e funzionalità che agevolano l’editing della sintassi markdown. La documentazione è consultabile al link https://code.visualstudio.com/docs/languages/markdown.
Il pannello struttura consente di navigare facilmente tra gli elementi “titoli” del file markdown.
La scorciatoia da tastiera Ctrl + Maiusc + V consente di alternare la visualizzazione del file di testo markdown e la sua anteprima formattata.
oppure la scorciatoia Ctrl + K, V apre l’anteprima affiancata.
Limitazioni anteprima di base di VS Code:
- ID titoli
- pannelli
- riquadro di testo non proporzionale
- note a pié pagina
- definizioni
- shortcode per le icone
- abbreviazioni (supporto parziale)
Inoltre non è possibile stampare o esportare in altro formato l’anteprima.
Tra le numerose estensioni dedicate al formato Markdown segnalo le più interessanti:
- Markdown Preview Enhanced: is an extension that provides you with many useful functionalities such as automatic scroll sync, math typesetting, mermaid, PlantUML, WebSequenceDiagrams, pandoc, PDF export, code chunk, presentation writer, etc.
- Markdown Preview Github Styling e GitHub Markdown Preview: Changes VS Code’s built-in markdown preview to match GitHub’s styling
- Markdown All in One: All you need for Markdown (keyboard shortcuts, table of contents, auto preview and more).
Sintassi Markdown
La guida di riferimento alla sintassi markdown è disponibile sul sito https://www.markdownguide.org:
Il markdown cheat sheet riassume tutte (o quasi) le regole della sintassi markdown. Da tenere sempre a portata di mano per imparare la sintassi scrivendo i propri documenti markdown.
Esportazione in PDF
Per esportare un documento markdown in PDF il suggerimento per ottenere il risultato migliore è installare l’estenzione di VS Code Markdown Preview Enhanced. Nelle impostazioni dell’anteprima si consiglia di scegliere il tema Light (atom-light.css) ed il tema light default per i code bloc.
Dopo aver visualizzato l’anteprima in VS Code dal menu contestuale scegliere la voce Open in browser. Quindi procedere alla stampa della pagina sulla stampante PDF (funzione già integrata nei browser) od ancora meglio – avendo installato sul PC il prodotto PDF24 – stampare sulla PDF24.