Inspringen in Markdown: geneste lijsten, alinea's en code

Om een Markdown-sublijst te laten inspringen, lijn je de markering uit onder het eerste teken van de tekst van het bovenliggende item. Voor - Hoofditem betekent dat twee spaties. Voor 1. Hoofditem zijn het er drie. Inspringing bepaalt de documentstructuur, dus spaties toevoegen aan een gewone alinea kan een heel ander effect hebben dan de visuele inspringing van een Word-alinea wijzigen.

Begin met dit voorbeeld in de Markdown-viewer:

- Projectdocumenten
  - Installatiehandleiding
  - Releaseopmerkingen
- Beoordelingschecklist

De installatiehandleiding en releaseopmerkingen moeten onder het item voor projectdocumenten verschijnen. De beoordelingschecklist moet op het buitenste niveau blijven.

Tel vanaf de inhoud van het bovenliggende item

Gebruik voor gewone lijstitems met één spatie na de markering deze uitlijningsrichtlijn:

Daarom werkt een algemene regel zoals "gebruik altijd twee spaties" niet voor genummerde lijsten. De GitHub-documentatie over geneste lijsten laat de uitlijning ten opzichte van de bovenliggende inhoud zien, ook met langere numerieke markeringen.

1. Bereid de release voor
   - Bevestig het versienummer.
   - Werk het wijzigingenlogboek bij.
2. Publiceer de documentatie

De geneste markeringen hebben drie spaties aan het begin. Als ze bij de linkermarge beginnen, starten ze een afzonderlijke lijst in plaats van bij de eerste genummerde stap te horen.

Werk je met een oudere Markdown-verwerker, bekijk het bestand dan ook daarin. De voorbeelden hier richten zich op parsing volgens CommonMark en GitHub Markdown; oudere implementaties kunnen geneste blokken anders herkennen.

Voeg een alinea toe binnen een lijstitem

Een langere uitleg heeft geen eigen opsommingsteken nodig. Laat een lege regel vrij en lijn de nieuwe alinea onder de tekst van het item uit:

1. Beoordeel de installatiehandleiding.

   Controleer of een nieuwe lezer de installatie kan voltooien zonder
   een intern document te openen.

2. Keur de releaseopmerkingen goed.

De toelichtende alinea hoort bij stap één. De twee bronregels lopen door, tenzij je een expliciete regelafbreking toevoegt.

Het weglaten van de drie spaties kan de genummerde lijst beëindigen en de uitleg in een gewone alinea veranderen. In sommige bewerkingsprocessen kan hierdoor ook de nummering van de volgende lijst opnieuw beginnen.

Hetzelfde patroon werkt met opsommingstekens:

- Installatiehandleiding

  Neem vereisten, installatieopdrachten en een verificatiestap op.
- Releaseopmerkingen

Gebruik een afzonderlijke alinea wanneer de uitleg meerdere zinnen bevat. Gebruik een sublijst wanneer de uitleg afzonderlijke onderdelen bevat die lezers individueel moeten kunnen scannen.

Zet code binnen een genummerde stap

Afgebakende code maakt de grenzen van een opdrachtvoorbeeld zichtbaar. Laat de openingsmarkering, inhoud en sluitingsmarkering inspringen om het blok binnen het lijstitem te houden:

1. Controleer de geïnstalleerde versie.

   ```sh
   node --version
   ```

   Noteer het resultaat in de beoordelingsnotities.

2. Voer de projectcontroles uit.

Hier begint de codeafbakening onder de eerste letter van Controleer. De alinea erna gebruikt dezelfde uitlijning en blijft daardoor ook binnen de eerste stap.

Als de volgende genummerde stap onderdeel van het codeblok wordt, controleer dan de sluitingsmarkering. Staat de code buiten de lijst, controleer dan de spaties vóór de afbakening. Zie de handleiding voor codeblokken voor taallabels en letterlijke backticks.

Waarom vier spaties tekst in code kunnen veranderen

Op het buitenste niveau van het document kunnen vier spaties vóór een regel, na een lege regel, een ingesprongen codeblok maken:

Een gewone alinea.

    Deze regel wordt als code weergegeven.

Dit is bedoelde Markdown-syntaxis, geen defecte instelling voor inspringen. De CommonMark-naslag voor ingesprongen codeblokken legt de rol van inspringing en blokgrenzen uit.

Een ingesprongen regel die direct op gewone alineatekst volgt, heeft andere parsingregels. Spaties invoegen is daarom geen betrouwbare manier om een visuele alinea-inspringing te maken. Binnen lijsten hangt het vereiste aantal spaties ook af van het omvattende item.

Gebruik voor een citaat een blokcitaat. Voor gewone tekst waarvan de eerste regel in een definitief rapport moet inspringen, houd je de Markdown als een normale alinea en pas je na export de alineaopmaak in Word toe. Zo blijft de bedoelde betekenis van de inhoud behouden.

Gebruik bij het oplossen van problemen bij voorkeur spaties

Tabs kunnen meerdere kolommen op het scherm innemen en verschillende editors kunnen ze op verschillende breedten weergeven. Als een lijst in de bron uitgelijnd lijkt maar verkeerd wordt weergegeven, maak dan witruimte zichtbaar in je editor en vervang tabs aan het begin door het vereiste aantal spaties.

Vervang tabs in codevoorbeelden niet zonder onderscheid. Daar kan witruimte onderdeel van het voorbeeld zelf zijn. Beperk het opschonen tot de Markdown-markeringen en vervolginspringing die de omliggende lijststructuur bepalen.

Gebruik geen herhaalde entiteiten voor vaste spaties om een geneste lijst na te bootsen. Dat kan de tekst in één voorbeeld verschoven laten lijken terwijl het onderliggende document uit losse, niet-gerelateerde alinea's blijft bestaan.

Controleer de structuur vóór export naar Word

Controleer een representatieve sectie met een bovenliggend item, een sublijst, een tweede alinea en een afgebakend codeblok. In de Markdown-naar-HTML-converter staat een echte geneste lijst binnen het bovenliggende lijstitem; alleen een visuele verschuiving legt die relatie niet vast.

Gebruik vervolgens de Markdown-naar-Word-converter en open het DOCX-bestand. Controleer of de nummering doorgaat zoals bedoeld en of opdrachten bij hun stappen blijven horen. De lijststijlen van Word kunnen een andere visuele afstand gebruiken dan de browser. Beoordeel daarom zowel de hiërarchie als het uiteindelijke uiterlijk van het document voordat je het deelt.