Dominar les Llistes Markdown: Estàndards de Sagnat CommonMark i GitHub Flavored Markdown (GFM)
La Base Tècnica del Processament de Llistes Markdown
Markdown s'ha establert com el llenguatge de marcat estàndard per a la documentació de programari modern, documents d'especificació tècnica, bases de coneixement personals i comunicació entre desenvolupadors. Tot i que les llistes d'un sol nivell amb pinyons (- element) i les llistes numerades (1. element) semblen simples, construir esquemes de documents profundament anidats introdueix una complexitat de format considerable. Diferents analitzadors de Markdown—com CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown i Pandoc—apliquen regles estrictes sobre la selecció de marcadors, la proporció de tabulacions i espais i el sagnat de subblocs.
Quan s'enganxen llistes entre diferents editors de text (com VS Code, Sublime Text, Xcode, Apple Notes o Microsoft Word), es produeixen errors de sagnat invisibles. Un sol espai quan falta en un subelement fa que el compilador de Markdown interpreti un node fill anidat com un element principal de primer nivell o com un bloc de paràgraf aïllat. El formatador de llistes anidades i sagnat d'Utiliome elimina aquestes anomalies d'anàlisi analitzant l'arbre de sintaxi abstracta (AST) del text i regenerant un Markdown estàndard i conformat amb les especificacions.
Regles de Sagnat: Directrius de 2 Espais vs 4 Espais
Un dels debats més freqüents en el disseny de documentació tècnica és si cal sagnar les subllistes utilitzant 2 espais o 4 espais per nivell jeràrquic. La tria depèn de l'especificació de l'analitzador Markdown objectiu:
La Regla de Sagnat de 2 Espais (Estàndard GFM i Prettier): En els ecosistemes moderns de documentació web com GitHub, Docusaurus, Nextra i Obsidian, 2 espais per nivell de sagnat és l'estàndard reconegut. Aquesta convenció alinea el contingut fill sota l'inici del text de l'element pare:
- Element de primer nivell 1 - Element fill anidat 1.1 - Element fill anidat 1.2 - Element net profundament anidat 1.2.1 - Element de primer nivell 2La Regla de Sagnat de 4 Espais (CommonMark Estricte i Python-Markdown): Les implementacions estrictes de CommonMark requereixen que els blocs fills, fragments de codi i llistes anidades dins de llistes ordenades tinguin un sagnat de 4 espais (o 1 tabulació completa) per garantir la contenció correcta del bloc pare:
1. Primer pas ordenat del flux de treball - Pinyó subassociat A - Pinyó subassociat B 2. Segon pas ordenat del flux de treballTrampes de Tabulació vs Espai: Barrejar caràcters de tabulació (
\t) amb espais ASCII (\x20) és la causa principal d'errors en la visualització de documentació Markdown. Els motors de renderitzat web interpreten les tabulacions de manera inconsistent (sovint com a 4 o 8 columnes), fent que els elements anidats desquadrin visualment. Utiliome converteix automàticament totes les tabulacions en cadenes d'espais uniformes segons la teva configuració.
Normalització de Marcadors i Correcció de Seqüències Ordenades
Markdown admet tres caràcters diferents per a llistes no ordenades: guions (-), asteriscs (*) i signes més (+). Tot i que tots tres produeixen elements HTML de llista no ordenada vàlids (<ul>), barrejar tipus de marcadors en un mateix document crea desordre visual i incompleix les comprovacions dels analitzadors de linter (com la regla MD004 de markdownlint).
A més, la numeració de les llistes ordenades sovint es trenca durant l'edició. Els autors solen enganxar elements al mig de seqüències numerades o confien en la sintaxi d'autoincrement 1.:
<!-- Entrada sense format / Amb errors -->
* Funcionalitat A
- Funcionalitat B
+ Funcionalitat C
1. Pas inicial
1. Segon pas (copiat de l'esborrany)
4. Pas desordenat
El formatador d'Utiliome normalitza tots els marcadors de llistes no ordenades al caràcter unificat que triïs (per exemple, unificant cada element a -) i renumera les seqüències ordenades consecutivament (1., 2., 3.) o les estandarditza a increments nets (1., 1., 1.) segons les guies d'estil del teu equip.