VSCode come editor markdown

VSCode supporta markdown in modo nativo e permette di visualizzarne l’anteprima senza lasciare l’editor. L’esperienza di scrittura in markdown però non è delle migliori perché le impostazioni predefinite si limitano ad evidenziare i titoli, il grassetto, il corsivo e poco altro. Per poter scrivere seriamente markdown, e renderlo leggibile mentre si lavora, VSCode ha bisogno di essere configurato e questo post spiega come farlo (evidenziando anche alcuni limiti dell’editor).

I file di configurazione di VSCode

Le modifiche mostrate di seguito possono essere fatte nel file locale di uno specifico progetto (es. .vscode/settings.json) oppure nel file globale per il vostro utente (su Linux ~/.config/Code/User/settings.json ). La scelta di modificare il primo o il secondo dipende dal fatto di volere queste impostazioni per la modifica di tutti i file markdown del vostro sistemo o no. Qualsiasi dei due scegliate di modificare, la loro struttura è la stessa perché sono due file JSON.

{
    // un file settings.json d'esempio di VSCode che disabilita la telemetria - un'ottima idea
    "telemetry.telemetryLevel": "off",
    "telemetry.feedback.enabled": false,
}

In realtà il formato usato per i file di configurazione di VSCode non è il JSON standard ma è un formato derivato chiamato JSON with comments perché, appunto, permette di inserire i commenti all’interno della sua struttura.

Testo leggibile

La prima configurazione da fare per migliorare la leggibilità del testo markdown è la scelta del font e l’interlinea. Se non avete preferenze sul font usate Fira Code che è libero, molto diffuso e ha le legature.¹

Molte distribuzioni Linux includono Fira Code tra i pacchetti ufficiali: per esempio su Fedora si installa con sudo dnf install fira-code-fonts. Esistono numeri font monospace ma solo alcuni di questi hanno il supporto alle legature. Un elenco è disponibile a questa pagina.

L’altro punto importante è l’interlinea: impostandola doppia, le righe di testo avranno più respiro e sarà più facile trovare gli errori. Per rendere queste modifiche specifiche solo all’editing dei file markdown, le dovremo inserire in un blocco apposito, come mostrato di seguito.

{
    // ...
    "[markdown]": {
        "editor.fontFamily": "Fira Code",
        "editor.fontLigatures": true, // opzionale - dipende dal font scelto
        "editor.lineHeight": 2,
    }
}

L’impostazione editor.fontLigatures non era strettamente necessaria ma attivandola facciamo in modo che il font utilizzi le legature (se le supporta).

Perché dobbiamo scrivere interi file markdown usando un font monospaced invece di usarlo solo nei blocchi di codice? Questo è un limite di VSCode: non è possibile usare font diversi nello stesso file a meno di hack pesanti. Questo problema è stato segnalato più volte a partire dal 2017 ma ancora non c’è stato nessuno sviluppo al riguardo.

Linee di testo e a capo (text wrap)

Quando scriviamo del testo non vogliamo doverci preoccupare della lunghezza delle frasi ma, allo stesso tempo, non vogliamo che l’eccessiva lunghezza di una linea faccia scorrere il testo fuori dall’area visibile (scroll orizzontale). Per risolvere questo problema abbiamo bisogno delle funzionalità di text wrapping cioè quelle che gestiscono per noi l’a capo, in automatico.

Esistono due tipi di wrapping: quello hard e quello soft. Il primo metodo, quando scrivendo raggiungiamo il limite sinistro dell’editor (semplificazione, vedi sotto), aggiunge un carattere di a capo nel testo e sposta il cursore alla linea successiva. Il secondo metodo, quello soft fa la stessa cosa ma senza aggiungere il carattere: si tratta di un a capo “virtuale”, solo visivo. Nella mia esperienza, il metodo soft è quello migliore, soprattutto se il testo deve poi essere salvato in git e simili (diff più pulite, ma è un argomento a parte di cui non parleremo ora).

Per fare in modo che VSCode mandi a capo il testo quando viene superata una certa lunghezza della riga, dobbiamo aggiungere altre quattro impostazioni.

{
    // ...
    "[markdown]": {
        // ...
        "editor.wordWrap": "wordWrapColumn",
        "editor.wordWrapColumn": 90, // al 90-esimo carattere va a capo
        "editor.wrappingIndent": "indent",

        "editor.rulers": [89], // righello visuale a dx - coerente con wordWrapColumn
    }
}

Con "editor.wordWrap": "wordWrapColumn" diciamo a VSCode di usare come limite destro del testo la “colonna” e che una volta che i caratteri raggiungono il suo bordo, devono andare a capo con il soft wrap (solo visuale). La colonna è tutto quello che intercorre tra il bordo sinistro dello spazio in cui scriviamo il testo, a quello destro. Assegnando il numero 90 a editor.wordWrapColumn indichiamo la posizione di questa colonna: al 90-esimo carattere da sinistra (può contenere quindi 89 caratteri). Infine, assegnando a editor.wrappingIndent il valore indent chiediamo che le parti della linea che finiranno a capo abbiamo un rientro visuale, così da capire a quale frase appartengono e migliorare la leggibilità.

La scelta della larghezza della colonna dipende da diversi fattori: dalla dimensione dello schermo usata, dalla dimensione del font e da come riusciamo a leggere meglio senza affaticarci.

L’ultima impostazione, chiamata editor.rulers, permette di mostrare sullo schermo uno o più “righelli” verticali (una semplice riga). Nel codice mostrato ne viene attivato uno solo, a 89 caratteri di distanza dal bordo sinistro dell’editor. Questo numero è coerente con la dimensione della colonna perché la riga verticale viene mostrata a destra dell'89-esimo carattere, che è proprio il limite massimo che abbiamo scelto.

Perché mostrare questo righello se il testo finisce in automatico a capo? La sua utilità è legata principalmente ai blocchi di codice che inseriamo nel markdown e che, di solito, vogliamo che non vadano a capo da soli. Se quello che scriviamo finirà il codice su una pagina web, in un pdf o stampato su carta, non vogliamo che la formattazione del codice venga rovinata dagli a capo. Quindi, conoscendo le caratteristiche del formato in cui convertiremo il markdown, possiamo visualizzare questo righello per lavorare con più precisione. Per semplicità e per avere una visualizzazione uniforme tra testo e codice, usiamo la stessa misura con cui viene mandato a capo anche il testo.

In realtà, più che “per semplicità”, si tratta di essere costretti: VSCode non permette di avere un righello visualizzato solo per i blocchi di codice di markdown, che è l’unico punto dove ci serve realmente. Averlo su tutta la pagina non disturba troppo ma non possiamo fare altrimenti.

Markdown hard line break

La specifica CommonMark prevede che due spazi alla fine di una di una riga siano interpretati come un hard line break. In pratica, scrivendo “una frase con due spazi finali. ” questi vengono convertiti da markdown in un a capo “forte” (es. <br> in HTML). Il semplice andare a capo viene interpretato da markdown come uno spazio da aggiungre o poco più. Per esempio, Riga 1.\nRiga 2 viene trasformato in HTML qualcosa di simile a <p>Riga 1. Riga 2</p>.

Visto che è molto probabile che la nostra configurazione di VSCode sia fatta per rimuovere gli spazi di troppo, è meglio aggiungere un’impostazione specifica per markdown, come suggerito dalla stessa documentazione.

{
    // ...
    "[markdown]": {
        // ...
        "files.trimTrailingWhitespace": false,
    }
}

Padding top e bottom

Un’impostazione molto spesso sottovalutata è quella relativa allo spazio vuoto intorno al testo. Quando scorriamo il documento verso l’inizio o verso la sua fine, il contenuto che si trova ai margini verticali estremi potrebbe sfuggirci a causa di un piccolo movimento mancante del mouse. In fondo alla pagina lasciamo una frasse che avevamo annotato e poi, senza che ce ne accorgiamo, viene pubblicata. Per evitarlo, o almeno per cercare di evitarlo, aggiungiamo dello spazio vuoto all’inizio e alla fine del documento. In questo modo, la fine del testo verrà mostrata prima di raggiungere la fine dello spazio che possiamo scorrere verticalmente con lo scroll.

{
    // ...
    "[markdown]": {
        // ...
        "editor.padding.bottom": 50,
        "editor.padding.top": 50,
    }
}

VSCode supporta la personalizzazione del padding verticale ma per quello orizzontale la strada da percorrere sembra ancora lunga.

Evidenziare la linea in cui ci troviamo

Per migliorare l’usabilità di VSCode mentre scriviamo, possiamo fare in modo che la linea in cui è posizionato il cursore venga evidenziata. Nella configurazione possiamo indicare due colori: uno per il bordo della linea e uno per lo sfondo. Per rendere efficace questa modifica è importante scegliere dei colori coerenti con il tema usato, in modo che la linea risalti sempre.

{
    // ...
    "workbench.colorTheme": "Default Light+", // vostro piacimento
    "workbench.colorCustomizations": {
        // in accordo con il tema usato
        "editor.lineHighlightBackground": "#e9f2fa",
        "editor.lineHighlightBorder": "#9292ac",
    },
    "[markdown]": {
        // ...

    }
}

Questa configurazione è supportata solo al livello generale e non è possibile indicarla per un tipo di file specifico. Quindi deve essere scritta al di fuori del blocco markdown.

Questo non è l’unico limite legato all’evidenziazione: ce n’è uno ancora più importante. Usando wordWrap, l’evidenziazione non si allargherà su più linee perché VSCode non è in grado di distinguere la linea fisica da quella logica.

Nascondere le informazioni inutili

Durante la scrittura non vogliamo vedere i numeri delle linee a sinistra, né la minimap a destra, né avere suggerimenti di autocompletamento che di solito producono solo errori nel testo. Per disabilitare tutte queste funzionalità è necessario aggiungere le configurazioni riportate di seguito.

{
    // ...
    "[markdown]": {
        // ...
        "editor.lineNumbers": "off",
        "editor.quickSuggestions": {
            "comments": "off",
            "strings": "off",
            "other": "off"
        },
        "editor.minimap.enabled": true,
        "editor.minimap.autohide": true
    }
}

La minimap non è completamente disattivata ma si mostra solo quando passiamo con il mouse nella sua zona di visualizzazione a destra. Rimane un ottimo strumento per scorrere il testo in cerca di qualcosa.

Concentrarsi solo sul testo

L’interfaccia di VSCode può essere ulteriormente pulita rimuovendo la barra laterele primaria a sinistra e la secondaria a destra. Per farlo basta fare click sulle icone relative a ognuna di queste due barre, oppure attraverso i menù View->Appearance->Primary Side Bar e View->Appearance->Secondary Side Bar.

Per scrivere senza distrazioni è fondamentale avere un solo file file aperto senza la visione divisa. Inoltre, impostando il layout centrato dal menù View->Appearance->Centered Layout il contenuto del file verrà visualizzato al centro dello schermo e non sul lato sinistro. Una volta fatto questo, potete allargare a piacere la colonna del layout centrato passando su uno dei suoi bordi e trascinandolo con il mouse. Trovare la dimensione giusta ci permetterà di allontanare la scrollbar di destra dal testo ed evitare che la minimap non sia attivata per errore con un movimento del mouse.

Possiamo andare oltre e, sempre dallo stesso menù, disabilitare la barra di stato in basso oppure il menù principale a sinistra. Se vogliamo far scomparire qualsiasi elemento dell’interfaccia senza disattivare uno per uno, possiamo attivare lo Zen Mode usando la sequenza di tasti CTRL+K Z (oppure il classico CTRL+SHIFT+P seguito da “Toggle Zen Mode”). Per uscirne basterà usare lo stesso metodo.

Evidenziare elementi del testo

L’ultima modifica a VSCode richiede l’utilizzo di un’estensione esterna: Highlight. Grazie a questa possiamo modificare lo stile delle parti del documento che ci interessano utilizzano delle regex. Nell’esempio riportato qui sotto, l’estensione viene usata per evidenziare il codice inline (prima regex) e i blocchi di codice markdown contenuti nelle sequenze di tre backtick. Nel primo caso aggiungiamo uno sfondo con un bordo al codice, mentre nel secondo ci limitiamo a evidenziare tutto il blocco. L’estensione permette di trasformare il testo secondo le nostre esigenze (nel mio setup ho specifiche regole per sequenze di caratteri da evidenziare).

{
    // ...
    "[markdown]": {
        // ...
    },
    "highlight.regexes": {
        "([^`])(`[^`]+?`)": {
            "filterLanguageRegex": "markdown",
            "regexFlags": "g",
            "filterFileRegex": ".*\\.md",
            "decorations": [{}, {
                "backgroundColor": "#0000001c",
                "borderColor": "#00000010",
                "borderStyle": "dashed",
                "borderWidth": "1px",
                "borderRadius": "3px"
            }, {}]
        },
        "(```.+?```)": {
            "regexFlags": "gs",
            "decorations": [{
                "backgroundColor": "#0000001c",
                "isWholeLine": true,
            }],
            "filterLanguageRegex": "markdown",
            "filterFileRegex": ".*\\.md"
        }
    }
}

Diff visuale tra le due configurazioni

Prima

Dopo

File di configurazione completo

{
    // ...
    "[markdown]": {
        "editor.fontFamily": "Fira Code",
        "editor.fontLigatures": true, // opzionale - dipende dal font scelto
        "editor.lineHeight": 2,

        "editor.wordWrap": "wordWrapColumn",
        "editor.wordWrapColumn": 90, // al 90-esimo carattere va a capo
        "editor.wrappingIndent": "indent",
        "editor.rulers": [89], // righello visuale a dx - coerente con wordWrapColumn

        "files.trimTrailingWhitespace": false,

        "editor.padding.bottom": 50,
        "editor.padding.top": 50,

        "editor.lineNumbers": "off",
        "editor.quickSuggestions": {
            "comments": "off",
            "strings": "off",
            "other": "off"
        },
        "editor.minimap.enabled": true,
        "editor.minimap.autohide": true
    },
    "workbench.colorTheme": "Default Light+", // vostro piacimento
    "workbench.colorCustomizations": {
        // in accordo con il tema usato
        "editor.lineHighlightBackground": "#e9f2fa",
        "editor.lineHighlightBorder": "#9292ac",
    },
    "highlight.regexes": {
        "([^`])(`[^`]+?`)": {
            "filterLanguageRegex": "markdown",
            "regexFlags": "g",
            "filterFileRegex": ".*\\.md",
            "decorations": [{}, {
                "backgroundColor": "#0000001c",
                "borderColor": "#00000010",
                "borderStyle": "dashed",
                "borderWidth": "1px",
                "borderRadius": "3px"
            }, {}]
        },
        "(```.+?```)": {
            "regexFlags": "gs",
            "decorations": [{
                "backgroundColor": "#0000001c",
                "isWholeLine": true,
            }],
            "filterLanguageRegex": "markdown",
            "filterFileRegex": ".*\\.md"
        }
    }
}

A ognuno la sua configurazione

Questa configurazione funziona per me e non è detto che risulti adeguata per tutti. Grazie alla informazioni contenute in questo post dovrebbe essere possibile creare una configurazione che rispecchi le proprie necessità. Nonostante le tante limitazioni, VSCode può diventare un editor markdown decente. L’utilizzo dell’estensione highlight permette di colmare alcune delle lacune dell’editor.