Scrittura agile con Markdown e Atom

La scrittura è fatta di parole ed un po’ di punteggiatura; testi in grassetto, note a piè di pagina, elenchi puntati etc… sono solo decorazioni che enfatizzano porzioni di testo; queste decorazioni, di solito sono applicate da uno specifico programma di videoscrittura e sono esportabili con difficoltà da un particolare programma ad un altro.

Grazie a Markdown, è possibile scrivere testi focalizzandosi sul contenuto ed applicare semplici regole di formattazione per strutturare il contenuto in modo da preservarne la leggibilità anche nel suo formato originario. All’inizio, il sistema di produzione dei testi proposto da Markdown, potrebbe sembrare “rudimentale” perché che ci siamo abituati a programmi come Word. Tuttavia, in questo modo si ottengono questi vantaggi:

1. indipendenza dal formato di file (non devi avere un programma come Word per aprire correttamente un file formattato con Markdown)
2. leggerezza (è un semplice file di testo contenente per il 99% parole e punteggiatura)
3. è facile produrre molteplici output (PDF, DOC, HTML, etc…)
4. il testo può risiedere in un semplice file o nel campo di un database (infatti i documenti Markdown sono spesso registrati direttamente in campi testo di DBMS SQL)
5. facilità di manutenzione del testo

Markdown è nato come script Perl programmato da John Gruber e Aaron Swarz nel 2004, ed ha riscosso un enorme successo per convertire testi in documenti HTML.

Per esempio, MarkDown legge il seguente testo…

Markdown
========

Download
--------

[Markdown 1.0.1](http://daringfireball.net/projects/downloads/Markdown_1.0.1.zip) (18 KB) — 17 Dec 2004

Introduction
------------
Markdown is a text-to-HTML conversion tool for web writers. 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).

…e lo converte in HTML:

<h1>Markdown</h1>
<h2>Download</h2>
<p><a href="http://daringfireball.net/projects/downloads/Markdown_1.0.1.zip">Markdown</a> 1.0.1 (18 KB) — 17 Dec 2004</p>
<h2>Introduction</h2>
<p>Markdown is a text-to-HTML conversion tool for web writers. 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).</p>

Nel corso degli anni Markdown è stato convertito in altri linguaggi ed è adottato da molti siti ed applicazioni, creando delle versioni personalizzate. Le varianti, sono diventate così tante che è sorto perfino il progetto CommonMark, col fine di definire una specifica di riferimento.

Per scrivere i testi di questo sito, ho usato il package Python-Markdown, che si installa in maniera molto semplice con pip.

pip install Markdown

La sintassi supportata da questa implementazione è fedele all’implementazione originale descritta su Daring Fireball.

Inoltre, Python-Markdown dispone di un’API per implementare delle estensioni; in particolare l’estensione CodeHilite permette di creare e formattare blocchi di codice con Pygments.

Pygments formatta i blocchi di codice seguendo dei “temi”; per conoscere i temi installati sul proprio sistema, si può eseguire questo comando da console:

$> pygmentize -L style

La formattazione e le estensioni da usare, sono configurate attraverso il modulo *markdown.extensions”, per esempio, Pelican consente di configurare Markdown in pelicanconf.py, come in questo esempio:

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {
            'css_class':'codehilite',
            'linenums':False,
            'pygments_style':'colorful'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
    },
    'output_format': 'html5',
}

Tuttavia, non è sempre agevole scrivere un documento di testo preoccupandosi di interpretare bene le convenzioni della sintassi Markdown; inoltre, i comuni editor di testo non dispongono di strumenti avanzati come il correttore ortografico e la visualizzazione di una anteprima del testo formattato.

Perciò, ho trovato molto utile usare un programma di videoscrittura in grado di salvare file di testo con la formattazione Markdown.

Fra i vari software disponibili, ho scelto di usare Atom, un elegante e potente editor di testo, multi piattaforma ed open source.

Atom è estensibile tramite plug-in, distribuiti nella forma di package. Attualmente esistono più di 6000 package: molti di questi, riguardano il supporto a MarkDown.

Il package Markdown Preview che fornisce una anteprima del documento formattato con Markdown è già disponibile con l’installazione predefinita; tuttavia, ho trovato molto utile aggiungere questi package:

1. Package Markdown Write che rende disponibili modelli per formattare il testo (per creare titoli, elenchi, etc…) ed inserire oggetti (immagini, files, etc…).
2. Markdown grammar che migliora il riconoscimento della formattazione di Markdown rispetto alle impostazioni predefinite ad aggiunge il supporto per alcuni “dialetti” ().

Atom dispone di un correttore ortografico multi lingua attraverso il package Spell Check; per impostare la lingua italiana occorre assegnare il valore “it-IT” alla voce “Locales” del menu “Settings”. Inoltre, occorre controllare che la voce “text.md” compaia nella voce “Grammars” e che sia spuntata la voce “Use locales”: se non lo é, occorre aggiungerlo per attivare il correttore ortografico per i file MarkDown.

Riferimenti

1. Markdown
2. CommonMark
3. Python Markdown Package
4. Wikipedia Markdown
5. Atom Text Editor
6. SitePoint - Best MarkDown editors
7. Mashable - Markdown tools
8. Zapier - Guide Markdown
9. Writing academic papers in plain text with Markdown and Jupyter notebook

Libri suggeriti

Guide gratuite:

1. Impara X in Y minuti
2. Scrivere e pubblicare in CommonMark alla buona
3. Atom Flight Manual