Rientri in Markdown: elenchi annidati, paragrafi e codice
Correggi i rientri Markdown con esempi di punti elenco annidati, elenchi numerati, paragrafi di continuazione e codice delimitato. Evita blocchi di codice accidentali.
Per far rientrare un sottoelenco Markdown, allinea il marcatore sotto il primo carattere del testo della voce principale. Per - Principale, servono due spazi. Per 1. Principale, ne servono tre. Il rientro controlla la struttura del documento, quindi aggiungere spazi a un normale paragrafo può avere un effetto molto diverso dal modificare il rientro visivo di un paragrafo Word.
Inizia con questo esempio nel visualizzatore Markdown:
- Documenti del progetto
- Guida all'installazione
- Note di rilascio
- Lista di controllo della revisione
La guida all'installazione e le note di rilascio dovrebbero apparire sotto la voce dei documenti del progetto. La lista di controllo della revisione dovrebbe rimanere al livello esterno.
Conta dal contenuto della voce principale
Per le normali voci di elenco scritte con uno spazio dopo il marcatore, usa questa guida di allineamento:
| La voce principale inizia con | Caratteri prima del testo | Rientro del sottoelenco |
|---|---|---|
- | 2 | 2 spazi |
1. | 3 | 3 spazi |
12. | 4 | 4 spazi |
100. | 5 | 5 spazi |
Ecco perché una regola generale come "usa sempre due spazi" non funziona per gli elenchi numerati. La documentazione GitHub sugli elenchi annidati illustra l'allineamento rispetto al contenuto principale, anche con marcatori numerici più lunghi.
1. Prepara il rilascio
- Conferma il numero di versione.
- Aggiorna il registro delle modifiche.
2. Pubblica la documentazione
I marcatori annidati hanno tre spazi iniziali. Se iniziano dal margine sinistro, avviano un elenco separato invece di appartenere al primo passaggio numerato.
Quando lavori con un vecchio elaboratore Markdown, visualizza l'anteprima del file anche in quello. Gli esempi qui si riferiscono all'analisi in stile CommonMark e al Markdown di GitHub; le implementazioni precedenti possono riconoscere diversamente i blocchi annidati.
Aggiungi un paragrafo in una voce di elenco
Una spiegazione più lunga non richiede un punto elenco proprio. Lascia una riga vuota, poi allinea il nuovo paragrafo sotto il testo della voce:
1. Revisiona la guida all'installazione.
Verifica che un nuovo lettore possa completare la configurazione senza
aprire un documento interno.
2. Approva le note di rilascio.
Il paragrafo esplicativo appartiene al primo passaggio. Le due righe del sorgente scorrono insieme, a meno che tu non aggiunga un'interruzione di riga esplicita.
Omettere i tre spazi può terminare l'elenco numerato e trasformare la spiegazione in un paragrafo normale. In alcuni flussi di modifica ciò può anche far ripartire la numerazione dell'elenco successivo.
Lo stesso schema funziona con i punti elenco:
- Guida all'installazione
Includi prerequisiti, comandi di configurazione e un passaggio di verifica.
- Note di rilascio
Usa un paragrafo separato quando la spiegazione contiene più frasi. Usa un sottoelenco quando contiene elementi distinti che i lettori devono poter esaminare individualmente.
Inserisci codice in un passaggio numerato
Il codice delimitato rende visibili i confini di un esempio di comando. Applica un rientro al delimitatore di apertura, al contenuto e al delimitatore di chiusura per mantenere il blocco nella voce di elenco:
1. Controlla la versione installata.
```sh
node --version
```
Annota il risultato nelle note di revisione.
2. Esegui i controlli del progetto.
Qui il delimitatore inizia sotto la prima lettera di Controlla. Il paragrafo successivo usa lo stesso allineamento, quindi rimane anch'esso nel primo passaggio.
Se il passaggio numerato successivo diventa parte del blocco di codice, controlla il delimitatore di chiusura. Se il codice appare fuori dall'elenco, controlla gli spazi iniziali del delimitatore. Consulta la guida ai blocchi di codice per le etichette dei linguaggi e gli accenti gravi letterali.
Perché quattro spazi possono trasformare il testo in codice
Al livello esterno del documento, dopo una riga vuota, quattro spazi prima di una riga possono creare un blocco di codice rientrato:
Un paragrafo normale.
Questa riga viene visualizzata come codice.
È una sintassi intenzionale di Markdown, non un controllo del rientro difettoso. Il riferimento CommonMark sui blocchi di codice rientrati spiega il ruolo del rientro e dei confini dei blocchi.
Una riga rientrata immediatamente successiva al testo di un normale paragrafo segue vincoli di analisi diversi, quindi inserire spazi non è un modo affidabile per creare un rientro visivo di paragrafo. Negli elenchi, gli spazi richiesti dipendono anche dalla voce che contiene il blocco.
Per una citazione, usa un blocco di citazione. Per il testo normale che richiede un rientro della prima riga in una relazione finale, mantieni un paragrafo normale in Markdown e applica la formattazione del paragrafo in Word dopo l'esportazione. Queste scelte preservano il significato previsto del contenuto.
Preferisci gli spazi durante il debug
Le tabulazioni possono occupare più colonne visualizzate e ogni editor può mostrarle con larghezze diverse. Se un elenco sembra allineato nel sorgente ma viene visualizzato male, mostra gli spazi bianchi nell'editor e sostituisci le tabulazioni iniziali con il numero di spazi necessario.
Non sostituire indiscriminatamente le tabulazioni negli esempi di codice. Lì gli spazi bianchi possono far parte dell'esempio stesso. Limita la pulizia ai marcatori Markdown e al rientro di continuazione che determinano la struttura dell'elenco circostante.
Evita di usare entità ripetute di spazio unificatore per imitare un elenco annidato. Potrebbero far apparire il testo spostato in un'anteprima lasciando però il documento sottostante come paragrafi senza relazione.
Verifica la struttura prima dell'esportazione in Word
Esamina una sezione rappresentativa contenente una voce principale, un sottoelenco, un secondo paragrafo e un blocco di codice delimitato. Nel convertitore da Markdown a HTML, un elenco realmente annidato è contenuto nella sua voce principale; un semplice spostamento visivo non stabilisce questa relazione.
Poi usa il convertitore da Markdown a Word e apri il DOCX. Verifica che la numerazione continui come previsto e che i comandi restino associati ai rispettivi passaggi. Gli stili di elenco di Word possono usare una spaziatura visiva diversa da quella del browser, quindi valuta sia la gerarchia sia l'aspetto finale del documento prima di condividerlo.