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

La sintaxis extendida Markdown es el conjunto de elementos de formato añadidos después de que John Gruber publicara la especificación original en 2004. Aquella especificación de 2004 definía 11 elementos básicos y dejaba fuera por completo las tablas, las notas al pie, las listas de tareas y el tachado. Proyectos posteriores cubrieron esos huecos: MultiMarkdown incorporó las tablas y las notas al pie en 2005, Pandoc llegó en 2006 con el mayor conjunto de extensiones de todos los procesadores, CommonMark estandarizó el núcleo en 2014 dejando margen para extensiones y GitHub publicó la especificación GFM en 2017. Todos los elementos de esta página se renderizan en la vista previa en tiempo real del editor, así que pegar un ejemplo durante 5 segundos te dice si tu aplicación de destino lo admite.

Matriz de compatibilidad

Ninguna aplicación admite los 12 elementos extendidos, así que comprueba la compatibilidad de tu destino antes de publicar. Los 4 destinos más habituales difieren de forma notable:

Un atajo práctico: las tablas, los bloques de código delimitados, el tachado y las listas de tareas se renderizan casi en cualquier sitio. Las listas de definición, el resaltado, el subíndice y el superíndice son los 4 elementos con más papeletas para fallar.

Tablas Markdown

Una tabla en Markdown separa las columnas con barras verticales y marca la fila de cabecera con una línea divisoria de 3 o más guiones. Las barras exteriores son opcionales en la mayoría de los parsers, pero mejoran la compatibilidad, así que consérvalas.

| 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 empuja a la derecha. El parser aplica esa alineación a todas las celdas de la columna. El número de guiones no tiene que coincidir entre columnas. Para escribir una barra vertical literal dentro de una celda, usa la entidad HTML |; GitHub también acepta el escape con barra invertida \|. Las celdas admiten formato en línea, como negrita o código, pero nunca elementos de bloque como listas o encabezados.

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

Bloques de código delimitados

Un bloque de código delimitado se abre y se cierra con 3 acentos graves y no necesita sangría, a diferencia de los bloques con 4 espacios de la especificación de 2004. Tres virgulillas funcionan como delimitador alternativo en la mayoría de los parsers.

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

Un identificador de lenguaje colocado justo después del delimitador de apertura activa el resaltado de sintaxis. highlight.js, la biblioteca que hay detrás de muchos renderizadores web, incluye definiciones para unos 200 lenguajes, y entre los identificadores habituales están python, js, json, bash y sql. Para mostrar un bloque de código dentro de otro bloque de código, usa 4 acentos graves en el delimitador exterior.

Es el elemento extendido con mayor compatibilidad. GitHub, Obsidian, Discord y Pandoc renderizan los bloques delimitados, y las 4 aplicaciones 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 punto del archivo, escrita como [^1]: seguida de la nota. El renderizador reúne todas las definiciones al final de la página y enlaza cada pareja 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 de salida sigue el orden del documento y no la etiqueta. Una nota al pie admite varios párrafos si los párrafos adicionales van sangrados 4 espacios bajo la definición.

MultiMarkdown estrenó las notas al pie en 2005, Pandoc y Obsidian las admiten al completo y GitHub añadió su renderizado en 2021. Discord no admite 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} genera el elemento HTML h2 con id="refunds". El ID se convierte en un ancla estable para enlaces y CSS.

## Refund Policy {#refunds}

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

El enlace es un enlace Markdown estándar con una almohadilla y el ID como destino. Las páginas externas llegan al mismo punto añadiendo #refunds a la URL completa de la página.

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

Listas de definición

Una lista de definición 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.

La salida es un elemento <dl> real con hijos <dt> y <dd>, algo que importa para los glosarios y para los lectores de pantalla. Varias líneas con dos puntos seguidas asignan varias definiciones a un mismo término.

La compatibilidad es escasa. PHP Markdown Extra definió la sintaxis, y tanto Pandoc como MultiMarkdown la interpretan. GitHub y Obsidian muestran las líneas con dos puntos como texto plano, y Discord hace lo mismo. El HTML <dl> en crudo es la alternativa fiable en GitHub.

Tachado

El tachado envuelve el texto con 2 virgulillas a cada lado, de modo que like this se renderiza como texto tachado. El elemento procede de GFM y la salida HTML es un elemento <del>.

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

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

La compatibilidad es casi universal. GitHub, Obsidian, Discord y Pandoc renderizan el tachado con 2 virgulillas.

Listas de tareas

Un elemento de lista de tareas Markdown empieza como un elemento de lista normal y añade corchetes: - [ ] marca una tarea pendiente 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 e hizo las casillas interactivas en issues y pull requests, donde un clic actualiza el Markdown subyacente. GitHub además las cuenta, así que un issue muestra el progreso como "2 of 3 tasks". Obsidian renderiza casillas pulsables en la vista de lectura y Pandoc convierte las listas de tareas en casillas HTML. Discord deja los corchetes como caracteres tal cual.

Emojis

Los emojis entran en un archivo Markdown de 2 maneras: pegando el carácter Unicode directamente o escribiendo un shortcode como :rocket: en las aplicaciones que los expanden. Los emojis pegados sobreviven en cualquier archivo UTF-8, así que 🎯 se muestra incluso donde los shortcodes fallan.

Release day :tada: went live at 9 am.

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

Resaltado

El resaltado envuelve el texto con 2 signos de igual, y ==like this== se renderiza con un fondo de rotulador, 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 renderiza por defecto y Pandoc lo interpreta con la extensión mark activada, disponible desde Pandoc 3.0 en 2023. GitHub y Discord imprimen los signos de igual literalmente. 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 virgulillas simples, como en H2O, y el superíndice los envuelve con acentos circunflejos simples, como en x^2^. Ambas formas proceden del conjunto 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 virgulilla y circunflejo, pero dejan pasar las etiquetas HTML, así que H₂O funciona en ambos. Discord no admite ninguna de las dos. Ojo con el conflicto de la virgulilla: una app con tachado de virgulilla simple tachará tu subíndice en lugar de bajarlo.

Enlaces automáticos de URL

El enlazado automático de URL convierte una dirección suelta como https://example.com en un enlace pulsable 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 enlace las URL sueltas, y Obsidian hace lo mismo en la vista de lectura. Pandoc mantiene el comportamiento desactivado salvo que se active la extensión autolink_bare_uris. Para impedir que una URL se convierta en enlace, envuélvela en acentos graves; el código en línea nunca se enlaza, así que https://example.com se queda como texto plano en ejemplos de configuración y dominios de relleno.

Preguntas frecuentes

¿La sintaxis extendida forma parte del Markdown oficial?

No. La especificación de 2004 define 11 elementos básicos, y todos los elementos de esta página proceden de sabores y procesadores posteriores. Markdown no tiene un organismo regulador, y por eso la compatibilidad cambia de una aplicación a otra.

¿Qué sabor de Markdown admite más sintaxis extendida?

Pandoc admite el abanico más amplio, con más de 30 extensiones de sintaxis opcionales, e interpreta 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 ve en GitHub pero no en Discord?

Discord implementa un subconjunto reducido de Markdown pensado para el chat y deja fuera las tablas, las notas al pie, las listas de tareas y las listas de definición. Su subconjunto cubre negrita, cursiva, tachado, encabezados y bloques de código delimitados. El contenido destinado a Discord debería ceñirse a esos 5 elementos.

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

Pega el elemento en la vista previa en tiempo real del editor online, que renderiza GFM más notas al pie en menos de 1 segundo, sin instalar nada en tu ordenador. Para cualquier otro destino, pega una muestra de 2 líneas en la propia aplicación; la matriz de compatibilidad cubre los 4 casos más habituales.