Hoja de referencia Markdown: los 21 elementos de sintaxis
Una hoja de referencia markdown, el clásico acordeón de toda la vida, es una página única que empareja cada elemento de markdown con su sintaxis exacta, para que puedas dar formato a un documento sin tener que revisar la documentación completa. Esta página reúne los 21 elementos en dos tablas: los 10 elementos básicos que John Gruber definió en la especificación original de 2004 y los 11 elementos extendidos que variantes posteriores como CommonMark (2014) y GitHub Flavored Markdown (2017) agregaron encima. Todos los ejemplos de sintaxis markdown de esta página funcionan también en el editor markdown en línea, donde la vista previa en vivo muestra el resultado renderizado mientras escribes.
Sintaxis básica
La sintaxis básica cubre los 10 elementos del diseño original de markdown de 2004, y todas las aplicaciones markdown los renderizan de forma idéntica. Estos 10 elementos resuelven la mayor parte de la escritura diaria: la estructura viene de los encabezados y las listas, el énfasis viene de las negritas y las cursivas, y las referencias vienen de los enlaces y las imágenes. Si un documento usa solo las filas de esta tabla, se renderiza correctamente en GitHub, en Obsidian, en Reddit, en Discord y en cualquier editor creado después de 2004.
| Elemento | Syntax | Resultado renderizado |
|---|---|---|
| Encabezado | # H1 / ## H2 / ### H3 | Títulos de sección de los niveles 1 a 6; un # por nivel |
| Negritas | **strong words** | strong words |
| Cursivas | *slanted words* | slanted words |
| Cita en bloque | > quoted line | Bloque de cita con sangría y un borde a la izquierda |
| Lista ordenada | 1. Step one 2. Step two | Lista numerada; la numeración se renderiza en secuencia |
| Lista desordenada | - First point - Second point | Lista con viñetas; * y + también funcionan como marcadores |
| Código | `inline code` | inline code en un recuadro monoespaciado |
| Línea horizontal | --- | Línea divisoria a todo lo ancho entre secciones |
| Enlace | [anchor text](https://example.com) | Hipervínculo al que puedes dar clic, con la etiqueta "anchor text" |
| Imagen |  | Imagen incrustada con texto alternativo para accesibilidad |
El marcador de encabezado necesita un espacio después del último #, y la línea horizontal necesita una línea en blanco arriba. Esos dos detalles causan la mayoría de las fallas de renderizado de la sintaxis básica.
Sintaxis extendida
La sintaxis extendida agrega 11 elementos que la especificación original de 2004 nunca incluyó, y su compatibilidad depende de qué variante de markdown implemente cada aplicación. Las tablas, los bloques de código delimitados y las listas de tareas llegaron con GitHub Flavored Markdown, que GitHub formalizó como especificación en 2017. Las notas al pie, las listas de definiciones y el resaltado vienen de otras variantes y se renderizan en menos aplicaciones.
| Elemento | Syntax | Resultado renderizado |
|---|---|---|
| Tabla | | Name | Role | | --- | --- | | Ada | Engineer | | Cuadrícula con fila de encabezado y columnas alineadas |
| Bloque de código delimitado | ```json { "id": 1 } ``` | Caja de código multilínea con coloreado de sintaxis opcional |
| Nota al pie | A claim.[^1] [^1]: The source. | Referencia numerada con la nota al final de la página |
| ID de encabezado | ## Pricing {#pricing} | Encabezado con un ancla personalizada para enlaces directos |
| Lista de definiciones | Term : Meaning of the term | Término en una línea y definición con sangría debajo |
| Tachado | ~~old figure~~ | |
| Lista de tareas | - [x] Ship the draft - [ ] Review edits | Lista de pendientes con casillas marcadas y sin marcar |
| Código de emoji | :tada: | El emoji correspondiente, 🎉 |
| Resaltado | ==key phrase== | Frase sobre un fondo de color |
| Subíndice | H~2~O | H₂O |
| Superíndice | x^2^ | x² |
La compatibilidad varía según la aplicación: GitHub renderiza tablas, bloques de código delimitados, listas de tareas, tachado, notas al pie y códigos de emoji, pero ignora el resaltado, el subíndice y el superíndice; Obsidian soporta tablas, notas al pie, listas de tareas, tachado y resaltado; Discord acepta negritas, cursivas, tachado y bloques de código, pero no soporta tablas ni notas al pie. Cuando no conoces la plataforma de destino, los 10 elementos básicos son la opción segura.
Cómo usar esta hoja de referencia
Busca el elemento en la columna izquierda, copia la sintaxis de la columna central y reemplaza el texto de ejemplo con tu propio contenido. La columna de resultado renderizado muestra cómo se ve la salida, así puedes confirmar que el elemento coincide con lo que buscas antes de copiarlo. Para cualquier fila de la tabla extendida, revisa primero la nota de compatibilidad; una nota al pie que se renderiza en GitHub desaparece en Discord.
La forma más rápida de verificar la sintaxis es pegarla en el editor markdown en línea. La vista previa en vivo renderiza cada elemento en milisegundos, así que una tabla rota o un marcador ** sin cerrar aparece de inmediato. Quienes escriben en markdown a diario suelen memorizar la tabla básica en una semana; la tabla extendida es la parte que conviene tener siempre a la mano.
Descargar e imprimir
Esta hoja de referencia cabe en una página A4 y está disponible como archivo .md, así que puedes guardar una copia en la app de notas de tu computadora o imprimirla como acordeón para tu escritorio. El archivo descargado es en sí mismo markdown válido, y las dos tablas se renderizan correctamente en cualquier aplicación que soporte las tablas de GFM. Ábrelo en el editor, en Obsidian o en un repositorio de GitHub y la referencia conserva su formato.
Preguntas frecuentes
¿Cuál es la diferencia entre la sintaxis básica y la sintaxis extendida de markdown?
Sintaxis básica significa los 10 elementos de la especificación original de 2004, y sintaxis extendida significa los 11 elementos que variantes posteriores agregaron. Todas las aplicaciones markdown soportan el conjunto básico. El conjunto extendido depende de la variante: CommonMark estandarizó el comportamiento central en 2014, y GFM agregó tablas, listas de tareas y tachado en su especificación de 2017.
¿Todas las aplicaciones markdown soportan la sintaxis extendida?
No. La compatibilidad con la sintaxis extendida difiere según la aplicación, y ninguna app renderiza los 11 elementos extendidos. GitHub omite el resaltado y el subíndice, Discord omite las tablas y las notas al pie, y Obsidian cubre el rango más amplio de las tres. Los documentos pensados para varias plataformas deberían apoyarse en la sintaxis básica más las tablas de GFM.
¿Es difícil aprender markdown?
No. Markdown tiene 21 elementos en total, y los 10 básicos cubren la mayoría de los documentos. Un # para los encabezados, ** para las negritas y - para las listas concentran la mayor parte del uso real. La mayoría de las personas escribe markdown con fluidez después de una sola sesión con un editor de vista previa en vivo, porque la vista previa corrige los errores al instante.