Formattatore Markdown

Cosa fa un formattatore Markdown

Il Markdown è permissivo. Puoi scrivere un punto elenco con -, * o +, l’enfasi con * o _, e un titolo con una riga di segni di uguale oppure con #. Questa libertà è comoda mentre scrivi, ma un file modificato da più persone finisce presto per mescolare tutti gli stili. Le tabelle perdono l’allineamento, mancano righe vuote e i diff diventano rumorosi.

Questo formattatore Markdown riscrive il sorgente in un unico stile coerente. È basato su Prettier, il formattatore che la maggior parte dei progetti JavaScript usa già per la documentazione, quindi il risultato coincide con quello che Prettier dà in VS Code o da riga di comando.

Come si usa

1. Incolla il Markdown nel riquadro a sinistra, oppure premi Apri file per caricare un file .md. Quando incolli, il testo viene formattato subito.
2. Premi Esempio se prima vuoi vedere un esempio.
3. Scegli il Rientro, la Larghezza riga e come gestire l’A capo del testo: Lascia com’è, Alla larghezza riga oppure Una riga per paragrafo.
4. Premi Formatta (o Ctrl e Invio) per rieseguirlo dopo una modifica.
5. Usa Copia o Scarica per prendere il risultato. Cancella svuota l’input.

Dopo la prima formattazione, il risultato segue quello che scrivi.

Prima e dopo

Ecco un breve file scritto con stili misti:

Project Notes
=============
* Install the tools
* Run the build
+ Deploy

|Name|Role|
|-|-|
|Ada|Admin|
|Linus|Editor|

Some *emphasis* and __bold__ text.

Il formattatore restituisce:

Project Notes
=============

- Install the tools
- Run the build

* Deploy

| Name  | Role   |
| ----- | ------ |
| Ada   | Admin  |
| Linus | Editor |

Some _emphasis_ and **bold** text.

Sono successe alcune cose. Ora dopo il titolo c’è una riga vuota. Il primo elenco usa -. Il grassetto usa ** e il corsivo _. Le colonne della tabella sono riempite di spazi in modo da allinearsi anche nel testo semplice. Nota che “Deploy” è rimasto separato: usava un punto elenco diverso, quindi il Markdown lo considera un secondo elenco, e il formattatore conserva questo significato assegnandogli un simbolo diverso.

Mandare a capo i paragrafi lunghi

Con A capo del testo impostato su Alla larghezza riga e una larghezza riga di 60, questo paragrafo:

Markdown files are easier to review when each paragraph follows the same rule for line length, because a diff then shows only the sentence that changed.

diventa:

Markdown files are easier to review when each paragraph
follows the same rule for line length, because a diff then
shows only the sentence that changed.

Una riga per paragrafo fa il contrario e riunisce le righe spezzate. Lascia com’è è l’impostazione sicura quando non sai cosa si aspetta il tuo team.

Cosa non viene toccato

Il formattatore cambia l’impaginazione, non il significato. Alcune cose le lascia volutamente stare:

• Blocchi di codice. Il codice dentro un blocco delimitato resta esattamente com’è. Un blocco marcato js che contiene const a={b:1} non viene riformattato. Per quello usa il formattatore JavaScript.
• Elenchi numerati. Se ogni voce inizia con 1., mantiene 1. su tutte le righe. Se li hai numerati 1, 2, 3, mantiene quella numerazione.
• Testo che non è sintassi valida. #Titolo senza spazio non è un titolo in CommonMark, quindi resta un normale paragrafo. Aggiungi lo spazio e diventa un titolo.
• HTML inline. I tag HTML dentro il Markdown restano come sono.

Consigli

• Formatta prima del commit. File coerenti significano che il diff di una pull request mostra solo le modifiche vere.
• Scegli una sola regola per l’a capo in tutto il repository. Mescolare file con e senza a capo causa diff enormi la prima volta che qualcuno li formatta.
• Costruire una tabella a mano è lento. Il generatore di tabelle Markdown ti dà una griglia in cui scrivere e accetta dati incollati dai fogli di calcolo.
• Ti serve il Markdown di una pagina web o di un file Word? Usa il convertitore da HTML a Markdown o il convertitore da Word a Markdown, poi riordina il risultato qui.

Altri modi per formattare il Markdown

• VS Code: installa l’estensione Prettier, apri un file .md ed esegui Format Document. Il risultato è identico a quello di questa pagina.
• Riga di comando: npx prettier --write README.md formatta un file e lo sovrascrive. Aggiungi --prose-wrap always per mandare a capo i paragrafi.
• Linting: markdownlint controlla regole di stile come i livelli dei titoli e la lunghezza delle righe. Segnala i problemi, mentre un formattatore sistema l’impaginazione al posto tuo. Molti progetti usano entrambi.

Limiti

Il formattatore segue CommonMark con le estensioni di GitHub come tabelle ed elenchi di attività. Le estensioni di altri strumenti, come i container personalizzati o i link in stile wiki, vengono trattate come testo normale e potrebbero ricevere una spaziatura diversa da quella che quello strumento si aspetta. Il front matter in cima al file (il blocco tra due righe ---) viene conservato. Anche i file molto grandi funzionano, ma la formattazione richiede più tempo perché avviene tutta sul tuo dispositivo.