Listas en Markdown: ordenadas, desordenadas y anidadas

Las listas son el elemento que más se rompe en Markdown, casi siempre por un problema de sangría o de líneas en blanco. Una vez entiendes esas dos reglas, dejan de dar problemas para siempre.

Listas desordenadas

Empieza cada línea con un asterisco, un guion o un signo de suma, seguido de un espacio.

- Primer elemento
- Segundo elemento
- Tercer elemento

• Primer elemento
• Segundo elemento
• Tercer elemento

Los tres símbolos son equivalentes y producen el mismo resultado:

* Con asterisco
- Con guion
+ Con signo de suma

Pero no los mezcles dentro de la misma lista. Aunque el Markdown original lo toleraba, CommonMark interpreta un cambio de símbolo como el comienzo de una lista nueva. Es decir, esto genera tres listas separadas, no una de tres elementos:

* Elemento A
- Elemento B
+ Elemento C

La convención mayoritaria es el guion -: se escribe sin pulsar Mayúsculas, se distingue bien del asterisco de la negrita y es lo que usan casi todos los formateadores automáticos.

Listas ordenadas

Número, punto y espacio:

1. Primer paso
2. Segundo paso
3. Tercer paso

1. Primer paso
2. Segundo paso
3. Tercer paso

Los números no tienen que ser correlativos

Esto sorprende, pero es intencionado. Markdown renumera automáticamente: solo mira el primer número para saber dónde empieza la lista, y el resto los ignora.

1. Primer paso
1. Segundo paso
1. Tercer paso

1. Primer paso
2. Segundo paso
3. Tercer paso

Escribir todo con 1. es una técnica muy práctica en documentos largos: puedes insertar o reordenar pasos sin tener que renumerar nada a mano. El resultado final sale correcto igualmente.

Si empiezas por otro número, la lista arranca ahí:

5. Quinto
6. Sexto

5. Quinto
6. Sexto

Listas anidadas

Para meter una lista dentro de otra, sangra los elementos hijos. La cantidad de espacios importa y es la causa del 90 % de las listas rotas.

- Fruta
    - Manzana
    - Pera
- Verdura
    - Espinaca
    - Brócoli

• Fruta
  • Manzana
  • Pera
• Verdura
  • Espinaca
  • Brócoli

La regla segura: cuatro espacios por nivel. Técnicamente CommonMark permite anidar con solo dos, pero el comportamiento varía entre procesadores y con cuatro funciona en todos. Si tu editor inserta tabulaciones, configúralo para que las convierta en espacios.

Puedes mezclar tipos al anidar:

1. Preparación
    - Reunir ingredientes
    - Precalentar el horno
2. Cocinado
    1. Mezclar
    2. Hornear 40 minutos

1. Preparación
   • Reunir ingredientes
   • Precalentar el horno
2. Cocinado
   1. Mezclar
   2. Hornear 40 minutos

Contenido dentro de un elemento

Aquí está la segunda regla que rompe listas. Para meter un párrafo adicional, un bloque de código o una cita dentro de un elemento de la lista, hacen falta dos cosas: una línea en blanco y la sangría alineada con el texto del elemento.

1. Instala las dependencias.

    Este paso puede tardar unos minutos la primera vez.

    ```
    npm install
    ```

2. Arranca el servidor.

1. Instala las dependencias.

   Este paso puede tardar unos minutos la primera vez.

2. Arranca el servidor.

Si te olvidas de la sangría, el párrafo sale fuera de la lista y además la parte en dos listas independientes: verás cómo la numeración se reinicia en 1.

Por qué se rompe una lista

Los cuatro fallos habituales, en orden de frecuencia:

Falta el espacio tras el símbolo. -Elemento no es una lista; - Elemento sí. Igual que con los encabezados.

Sangría insuficiente o inconsistente. Mezclar dos y cuatro espacios, o tabulaciones con espacios, produce resultados impredecibles. Elige cuatro espacios y sé consistente.

Falta la línea en blanco antes de la lista. Muchos procesadores exigen una línea vacía entre el párrafo anterior y el primer elemento. Sin ella, la lista puede quedar absorbida por el párrafo.

Cambio de símbolo a mitad. Como se ha visto, corta la lista en dos.

Listas de tareas

GitHub Flavored Markdown añade las casillas de verificación, que son listas desordenadas con un [ ] o [x] al principio:

- [x] Escribir el borrador
- [ ] Revisar

Tienen su propia página con el detalle completo: casillas de verificación.

Un apunte sobre el espacio entre elementos

Puede que hayas visto listas que salen “apretadas” y otras más separadas. No es casualidad: si dejas una línea en blanco entre los elementos, Markdown pasa a considerarla una lista suelta y envuelve cada elemento en su propio <p>, lo que añade separación vertical.

- Lista apretada
- Sin líneas en blanco

- Lista suelta

- Con líneas en blanco

Visualmente cambia bastante. Si tu lista sale con más aire del esperado, revisa si se te ha colado una línea en blanco.

Compatibilidad

Las listas básicas funcionan en todas partes. Lo que varía entre procesadores es el nivel de sangría exigido para anidar y el tratamiento de las listas sueltas. Con cuatro espacios y consistencia, no tendrás problemas en ningún sitio.

Pruébalo

Las listas anidadas son justo el caso donde una vista previa ahorra tiempo. Pega tu documento en el previsualizador de Markdown para ver dónde se rompe la sangría, o conviértelo a HTML para inspeccionar las etiquetas <ul>, <ol> y <li> generadas.