Sangría en Markdown: listas anidadas, párrafos y código
Corrige la sangría de Markdown con ejemplos de viñetas anidadas, listas numeradas, párrafos de continuación y código delimitado. Evita bloques de código accidentales.
Para aplicar sangría a una sublista de Markdown, alinea su marcador bajo el primer carácter del texto del elemento superior. Para - Principal, eso significa dos espacios. Para 1. Principal, significa tres. La sangría controla la estructura del documento, por lo que añadir espacios a un párrafo normal puede tener un efecto muy distinto de cambiar la sangría visual de un párrafo en Word.
Empieza con este ejemplo en el visor de Markdown:
- Documentos del proyecto
- Guía de instalación
- Notas de la versión
- Lista de comprobación de revisión
La guía de instalación y las notas de la versión deberían aparecer bajo el elemento de documentos del proyecto. La lista de comprobación de revisión debería mantenerse en el nivel exterior.
Cuenta desde el contenido del elemento superior
Para elementos de lista habituales con un espacio después del marcador, usa esta guía de alineación:
| El elemento superior empieza con | Caracteres antes de su texto | Sangría de la sublista |
|---|---|---|
- | 2 | 2 espacios |
1. | 3 | 3 espacios |
12. | 4 | 4 espacios |
100. | 5 | 5 espacios |
Por eso una regla general como «usa siempre dos espacios» falla con listas numeradas. La documentación de listas anidadas de GitHub muestra la alineación respecto al contenido superior, incluidos los marcadores numéricos más largos.
1. Prepara la publicación
- Confirma el número de versión.
- Actualiza el registro de cambios.
2. Publica la documentación
Los marcadores anidados tienen tres espacios iniciales. Si empiezan en el margen izquierdo, inician una lista independiente en lugar de pertenecer al primer paso numerado.
Si trabajas con un procesador Markdown antiguo, previsualiza también el archivo en él. Los ejemplos de esta página están pensados para el análisis de estilo CommonMark y GitHub Markdown; las implementaciones antiguas pueden reconocer los bloques anidados de otro modo.
Añade un párrafo dentro de un elemento de lista
Una explicación más larga no necesita una viñeta propia. Deja una línea en blanco y alinea el párrafo nuevo bajo el texto del elemento:
1. Revisa la guía de instalación.
Confirma que una persona nueva pueda completar la configuración sin
abrir un documento interno.
2. Aprueba las notas de la versión.
El párrafo explicativo pertenece al primer paso. Sus dos líneas del archivo fuente se muestran seguidas, salvo que añadas un salto de línea explícito.
Omitir los tres espacios puede cerrar la lista numerada y convertir la explicación en un párrafo normal. En algunos flujos de edición, esto también puede hacer que la siguiente lista reinicie la numeración.
El mismo patrón funciona con viñetas:
- Guía de instalación
Incluye requisitos previos, comandos de configuración y un paso de verificación.
- Notas de la versión
Usa un párrafo separado cuando la explicación contenga varias frases. Usa una sublista cuando contenga elementos distintos que los lectores deban examinar individualmente.
Coloca código dentro de un paso numerado
El código delimitado hace visibles los límites de un ejemplo de comandos. Aplica sangría al delimitador de apertura, al contenido y al delimitador de cierre para mantener el bloque dentro del elemento de lista:
1. Comprueba la versión instalada.
```sh
node --version
```
Anota el resultado en las notas de revisión.
2. Ejecuta las comprobaciones del proyecto.
Aquí el delimitador empieza bajo la primera letra de Comprueba. El párrafo posterior usa la misma alineación, de modo que también permanece dentro del primer paso.
Si el siguiente paso numerado pasa a formar parte del bloque de código, revisa el delimitador de cierre. Si el código aparece fuera de la lista, revisa los espacios iniciales del delimitador. Consulta la guía de bloques de código para las etiquetas de lenguaje y los acentos graves literales.
Por qué cuatro espacios pueden convertir texto en código
En el nivel exterior del documento, después de una línea en blanco, cuatro espacios antes de una línea pueden crear un bloque de código con sangría:
Un párrafo normal.
Esta línea se muestra como código.
Es una sintaxis intencionada de Markdown, no un fallo del control de sangría. La referencia de bloques de código con sangría de CommonMark explica la función de la sangría y de los límites de bloque.
Una línea con sangría inmediatamente después del texto de un párrafo normal está sujeta a otras reglas de análisis, por lo que insertar espacios no es una forma fiable de crear una sangría visual de párrafo. Dentro de las listas, los espacios necesarios también son relativos al elemento que contiene el bloque.
Para una cita, usa una cita en bloque. Para texto normal que necesite sangría de primera línea en un informe final, conserva un párrafo normal en Markdown y aplica el formato de párrafo en Word después de exportar. Esas opciones preservan el significado previsto del contenido.
Prefiere espacios al depurar
Las tabulaciones pueden ocupar varias columnas en pantalla y cada editor puede mostrarlas con anchos distintos. Si una lista parece alineada en el código fuente pero se muestra mal, activa la visualización de espacios en blanco en el editor y sustituye las tabulaciones iniciales por el número necesario de espacios.
No sustituyas indiscriminadamente las tabulaciones dentro de los ejemplos de código. Allí, el espacio en blanco puede formar parte del propio ejemplo. Limita la limpieza a los marcadores de Markdown y a la sangría de continuación que determinan la estructura de la lista circundante.
Evita repetir entidades de espacio de no separación para imitar una lista anidada. Eso puede desplazar visualmente el texto en una vista previa y dejar el documento subyacente como párrafos sin relación.
Verifica la estructura antes de exportar a Word
Revisa una sección representativa que contenga un elemento superior, una sublista, un segundo párrafo y un bloque de código delimitado. En el conversor de Markdown a HTML, una lista realmente anidada está contenida dentro de su elemento de lista superior; un desplazamiento visual por sí solo no establece esa relación.
Después usa el conversor de Markdown a Word y abre el DOCX. Comprueba que la numeración continúe como esperas y que los comandos sigan asociados a sus pasos. Los estilos de lista de Word pueden usar un espaciado visual distinto del navegador, así que evalúa tanto la jerarquía como el aspecto final del documento antes de compartirlo.