Markdown-lijsten Beheersen: CommonMark & GitHub Flavored Markdown (GFM) Inspringstandaarden
De Technische Basis van Markdown Lijst-Rendering
Markdown heeft zich gevestigd als de standaard opmaaktaal voor moderne softwaredocumentatie, technische specificaties, persoonlijke kennisbanken en communicatie tussen ontwikkelaars. Hoewel eenvoudige opsommingslijsten (- item) en genummerde lijsten (1. item) eenvoudig lijken, brengt het bouwen van diep geneste documentstructuren aanzienlijke opmaakcomplexiteit met zich mee. Verschillende Markdown-parsers—zoals CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown en Pandoc—hanteren strenge regels met betrekking tot de keuze van opsommingstekens, verhoudingen tussen tabs en spaties en de inspringing van subblokken.
Wanneer lijsten worden gekopieerd tussen verschillende teksteditors (zoals VS Code, Sublime Text, Xcode, Apple Notes of Microsoft Word), ontstaan er onzichtbare inspringfouten. Eén ontbrekende spatie bij een sub-item zorgt ervoor dat de Markdown-compiler een genest kind-element interpreteert als een hoofditem op het hoogste niveau of als een afzonderlijke paragraaf. De Geneste Lijst & Inspringing Formatter van Utiliome verwijdert deze printfouten door de abstracte syntaxboom (AST) van de invoertekst te analyseren en gestandaardiseerde, specificatie-conforme Markdown te genereren.
Inspringregels: 2 Spaties vs. 4 Spaties
Een van de meest voorkomende discussies bij het ontwerpen van technische documentatie is of sublijsten moeten worden ingesprongen met 2 spaties of 4 spaties per hiërarchisch niveau. De keuze hangt af van de doel-Markdown-parserspecificatie:
De 2-Spaties Inspringregel (Standaard GFM & Prettier): In moderne web-documentatie-ecosystemen zoals GitHub, Docusaurus, Nextra en Obsidian is 2 spaties per inspringniveau de erkende standaard. Deze conventie lijnt de onderliggende inhoud uit onder het begin van de tekst van het bovenliggende item:
- Item op hoogste niveau 1 - Genest kind-item 1.1 - Genest kind-item 1.2 - Diep genest kleinkind-item 1.2.1 - Item op hoogste niveau 2De 4-Spaties Inspringregel (Strikte CommonMark & Python-Markdown): Strikte CommonMark-implementaties vereisen dat subblokken, code-snippets en geneste lijsten binnen genummerde lijsten met 4 spaties (of 1 volledige tab) worden ingesprongen om een correcte insluiting in het hoofdblok te garanderen:
1. Eerste geordende stap in workflow - Geassocieerd sub-item A - Geassocieerd sub-item B 2. Tweede geordende stap in workflowValkuilen bij Tabs vs. Spaties: Het mengen van fysieke tabtekens (
\t) met ASCII-spaties (\x20) is de belangrijkste oorzaak van kapotte Markdown-documentatieweergave. Web-rendering-engines vertalen tabs op een inconsistente manier (vaak als 4 of 8 kolommen), waardoor geneste items visueel uit hun uitlijning springen. Utiliome converteert automatisch alle tabtekens naar uniforme spaties op basis van uw voorkeursinstellingen.
Normaliseren van Opsommingstekens & Herstellen van Geordende Volgordes
Markdown ondersteunt drie verschillende tekens voor ongeordende lijsten: koppeltekens (-), asterisken (*) en plustekens (+). Hoewel alle drie geldige HTML-elementen voor ongeordende lijsten (<ul>) genereren, veroorzaakt het mengen van typen tekens in hetzelfde document visuele rommel en mislukken automatische linter-checks (zoals regel MD004 van markdownlint).
Bovendien raakt de nummering van geordende lijsten vaak beschadigd tijdens het bewerken. Auteurs plakken vaak items in het midden van genummerde reeksen of vertrouwen op automatische 1. syntaxis:
<!-- Ongeformatteerde / Foutieve Invoer -->
* Functie A
- Functie B
+ Functie C
1. Eerste stap
1. Tweede stap (gekopieerd uit concept)
4. Stap buiten volgorde
De formatter van Utiliome normaliseert alle ongeordende opsommingstekens naar het door u gekozen karakter (bijvoorbeeld door elk item te standaardiseren naar -) en hernummert geordende reeksen opeenvolgend (1., 2., 3.) of standaardiseert ze naar enkele cijfers (1., 1., 1.) op basis van de richtlijnen van uw team.