Guía de sintaxis extendida Markdown: tablas, notas al pie y listas de tareas

La sintaxis extendida Markdown es el conjunto de elementos de formato que se agregaron después de que John Gruber publicó la especificación original en 2004. La especificación de 2004 definió 11 elementos básicos y dejó completamente fuera las tablas, las notas al pie, las listas de tareas y el texto tachado. Proyectos posteriores llenaron esos huecos: MultiMarkdown trajo las tablas y las notas al pie en 2005, Pandoc llegó en 2006 con el paquete de extensiones más grande de todos los procesadores, CommonMark estandarizó el núcleo en 2014 con espacio para extensiones y GitHub publicó la especificación GFM en 2017. Cada elemento de esta página se despliega en la vista previa en vivo del editor, así que con pegar tu ejemplo tardas 5 segundos en saber si tu app destino lo soporta.

Tabla de soporte

Ninguna aplicación soporta los 12 elementos extendidos, así que checa el soporte de tu destino antes de publicar. Los 4 destinos más comunes se comportan muy diferente:

Un atajo práctico: las tablas, los bloques de código cercados, el texto tachado y las listas de tareas se despliegan casi en cualquier lugar. Las listas de definiciones, el resaltado, el subíndice y el superíndice son los 4 elementos con más probabilidad de fallar.

Tablas Markdown

Una tabla en Markdown separa las columnas con barras verticales (pipes) y marca la fila de encabezado con una línea divisoria de 3 o más guiones. Los pipes exteriores son opcionales en la mayoría de los parsers, pero mejoran la compatibilidad, así que déjalos.

| Feature | Status |
| :------ | -----: |
| Export  | Done   |
| Sync    | Open   |

Los dos puntos en la fila divisoria controlan la alineación. :--- alinea la columna a la izquierda, :---: la centra y ---: la manda a la derecha. El parser aplica la alineación a todas las celdas de esa columna. La cantidad de guiones no necesita coincidir entre columnas. Para imprimir un pipe literal dentro de una celda, escribe la entidad HTML |; GitHub también acepta el escape con diagonal invertida \|. Las celdas aceptan formato en línea, como negritas y código, pero nunca elementos de bloque como listas o encabezados.

MultiMarkdown introdujo la sintaxis en 2005 y GFM la adoptó en 2017. GitHub, GitLab, Obsidian y Pandoc despliegan tablas. Discord no.

Bloques de código cercados

Un bloque de código cercado abre y cierra con 3 backticks y no necesita sangría, a diferencia de los bloques con 4 espacios de la especificación de 2004. Tres tildes (~) funcionan como cerca alternativa en la mayoría de los parsers.

```python
def total(items):
    return sum(items)
```

Un identificador de lenguaje colocado justo después de la cerca de apertura prende el resaltado de sintaxis. highlight.js, la librería detrás de muchos renderizadores web, trae definiciones para cerca de 200 lenguajes, y entre los identificadores comunes están python, js, json, bash y sql. Para mostrar un bloque de código dentro de otro bloque de código, haz la cerca exterior de 4 backticks.

Es el elemento extendido con el soporte más amplio de todos. GitHub, Obsidian, Discord y Pandoc despliegan los bloques cercados, y las 4 apps aplican el resaltado por lenguaje.

Notas al pie

Una nota al pie en Markdown tiene 2 partes: un marcador de referencia en el cuerpo del texto, escrito como [^1], y una definición colocada en cualquier parte del archivo, escrita como [^1]: seguida de la nota. El renderizador junta todas las definiciones al final de la página y vincula cada par en ambas direcciones.

The claim has a published source.[^1]

[^1]: Smith, 2024, p. 41.

Los identificadores pueden ser palabras además de números, y [^note] se comporta exactamente igual que [^1], porque la numeración final sigue el orden del documento y no la etiqueta. Una nota al pie puede tener varios párrafos si los párrafos extra van con sangría de 4 espacios debajo de la definición.

MultiMarkdown lanzó las notas al pie en 2005, Pandoc y Obsidian las soportan por completo y GitHub agregó su despliegue en 2021. Discord no soporta notas al pie.

IDs de encabezado

Un ID de encabezado personalizado va entre llaves al final de la línea del encabezado, y ## Refund Policy {#refunds} produce el elemento HTML h2 con id="refunds". El ID se vuelve un ancla estable para vínculos y CSS.

## Refund Policy {#refunds}

Jump straight to [the refund policy](#refunds).

El vínculo es un vínculo Markdown estándar con un símbolo de gato (#) y el ID como destino. Las páginas externas llegan al mismo punto cuando se agrega #refunds a la URL completa de la página.

Pandoc y PHP Markdown Extra procesan la forma con llaves. GitHub la ignora, pero genera IDs automáticos a partir del texto del encabezado, así que un vínculo a #refund-policy sigue funcionando ahí. Obsidian usa su propio patrón [[Note#Heading]] para vincular encabezados. Discord despliega encabezados en los mensajes, pero no tiene sistema de anclas.

Listas de definiciones

Una lista de definiciones empareja un término con 1 o más definiciones: el término va solo en una línea y cada definición empieza en la línea siguiente con dos puntos y un espacio.

Markdown
: A plain-text formatting syntax released in 2004.

Parser
: Software that converts markdown into HTML.
: Also called a processor.

El resultado es un elemento <dl> real con hijos <dt> y <dd>, lo cual importa para glosarios y para lectores de pantalla. Varias líneas con dos puntos, una tras otra, le dan varias definiciones a un mismo término.

El soporte es limitado. PHP Markdown Extra definió la sintaxis, y tanto Pandoc como MultiMarkdown la procesan. GitHub y Obsidian muestran las líneas con dos puntos como texto plano, y Discord hace lo mismo. El HTML <dl> directo es el respaldo confiable en GitHub.

Texto tachado

El tachado envuelve el texto con 2 tildes de cada lado, de modo que like this se despliega como texto cruzado por una línea. El elemento viene de GFM y la salida HTML es un elemento <del>.

~~Ship v2 on Friday.~~ Moved to Monday.

GitHub también acepta una sola tilde por lado. Quédate con 2 por portabilidad, porque una tilde sola significa subíndice en Pandoc y una diferencia de 1 carácter voltea el significado.

El soporte es casi universal. GitHub, Obsidian, Discord y Pandoc despliegan el tachado con 2 tildes.

Listas de tareas

Un elemento de lista de tareas Markdown empieza como un elemento de lista normal y agrega corchetes: - [ ] marca una tarea abierta y - [x] marca una terminada. El espacio dentro de los corchetes vacíos es obligatorio.

- [x] Draft the outline
- [x] Write the copy
- [ ] Publish the page

GitHub introdujo la sintaxis en 2013 y volvió interactivas las casillas en issues y pull requests, donde dar clic actualiza el Markdown de fondo. GitHub además las cuenta, así que un issue reporta el avance como "2 of 3 tasks". Obsidian despliega casillas cliqueables en la vista de lectura y Pandoc convierte las listas de tareas en casillas HTML. Discord deja los corchetes como caracteres escritos tal cual.

Emoji

Los emoji entran a un archivo Markdown de 2 formas: pegas el carácter Unicode directamente o escribes un shortcode como :rocket: en las aplicaciones que expanden shortcodes. Los emoji pegados sobreviven en cualquier archivo UTF-8, así que 🎯 se ve incluso donde los shortcodes fallan.

Release day :tada: went live at 9 am.

Un shortcode envuelve el nombre de un emoji entre 2 pares de dos puntos. GitHub expande aproximadamente 1,800 shortcodes, y Discord expande su propio conjunto más los emoji personalizados de cada servidor. Obsidian necesita un complemento de la comunidad para los shortcodes, aunque muestra los emoji pegados de forma nativa, y Pandoc los expande solo con su extensión de emoji activada. Los nombres cambian entre plataformas, así que un shortcode que funciona en GitHub no está garantizado en ningún otro lado.

Resaltado

El resaltado envuelve el texto con 2 signos de igual, y ==like this== se despliega con un fondo estilo marcatextos, normalmente amarillo. La salida HTML es un elemento <mark>.

The deadline moved to ==14 March== at noon.

Es uno de los elementos extendidos menos portables. Obsidian lo despliega por defecto y Pandoc lo procesa cuando la extensión mark está habilitada, disponible desde Pandoc 3.0 en 2023. GitHub y Discord imprimen los signos de igual de forma literal. Donde la sintaxis falla, la etiqueta <mark> funciona en cualquier renderizador que deje pasar el HTML, lo que incluye los readme de GitHub.

Subíndice y superíndice

El subíndice envuelve los caracteres con tildes simples, como en H2O, y el superíndice los envuelve con acentos circunflejos simples, como en x^2^. Ambas formas vienen del paquete de extensiones de Pandoc y no de ningún sabor web común.

H~2~O freezes at 0 degrees.
E = mc^2^ dates from 1905.

Pandoc los convierte en elementos <sub> y <sup>. GitHub y Obsidian ignoran las formas con tilde y circunflejo, pero dejan pasar las etiquetas HTML, así que H₂O funciona en ambos. Discord no soporta ninguno de los dos. Aguas con el choque de tildes: una app con tachado de tilde simple va a tachar tu subíndice en lugar de bajarlo.

Vínculos automáticos de URL

El vinculado automático de URL convierte una dirección suelta como https://example.com en una liga en la que puedes dar clic, sin necesidad de corchetes. GFM formalizó este comportamiento como la extensión autolink en su especificación de 2017.

Full docs at https://example.com/docs

GitHub y Discord convierten en vínculo las URL sueltas, y Obsidian hace lo mismo en la vista de lectura. Pandoc mantiene el comportamiento apagado a menos que se habilite la extensión autolink_bare_uris. Para evitar que una URL se convierta en vínculo, envuélvela en backticks; el código en línea nunca se vincula, así que https://example.com se queda como texto plano en ejemplos de configuración y dominios de relleno.

Preguntas frecuentes

¿La sintaxis extendida es parte del Markdown oficial?

No. La especificación de 2004 define 11 elementos básicos, y todos los elementos de esta página vienen de sabores y procesadores posteriores. Markdown no tiene un organismo que lo regule, y por eso el soporte cambia de una aplicación a otra.

¿Cuál sabor de Markdown soporta más sintaxis extendida?

Pandoc soporta el rango más amplio, con más de 30 extensiones de sintaxis opcionales, y procesa los 12 elementos de esta página. GFM es el objetivo más práctico para publicar en la web, porque GitHub, GitLab y la mayoría de los editores modernos lo siguen.

¿Por qué una tabla se despliega en GitHub pero no en Discord?

Discord implementa un subconjunto reducido de Markdown hecho para chat y deja fuera las tablas, las notas al pie, las listas de tareas y las listas de definiciones. Su subconjunto cubre negritas, cursivas, tachado, encabezados y bloques de código cercados. El contenido que va para Discord debería quedarse dentro de esos 5 elementos.

¿Cómo pruebo la sintaxis extendida antes de publicar?

Pega el elemento en la vista previa en vivo del editor en línea, que despliega GFM más notas al pie en menos de 1 segundo, sin instalar nada en tu computadora. Para cualquier otro destino, pega una muestra de 2 líneas en la app final; la tabla de soporte cubre los 4 casos más comunes.