CommonMark vs GFM: ¿las tablas forman parte de la especificación principal?

En resumen: CommonMark vs GFM

• CommonMark es la especificación estándar de Markdown. Define únicamente la sintaxis principal (encabezados, listas, énfasis, enlaces, imágenes, código y citas) y deja fuera las extensiones de forma deliberada.
• GFM (GitHub Flavored Markdown) es un dialecto que la especificación de GFM describe como un "superconjunto estricto" de CommonMark. Añade cinco extensiones por encima: tablas, tachado, listas de tareas, autoenlaces extendidos y HTML sin procesar no permitido.
• Las funciones de GitHub.com que la gente asocia con el Markdown de GitHub (avisos como [!NOTE], atajos de emoji, @menciones, referencias a issues, diagramas Mermaid, fórmulas matemáticas, notas al pie) no están en la especificación de GFM. Son una capa propia de GitHub.com y, por lo general, no funcionan fuera de GitHub.
• Que un único salto de línea suave se convierta en <br> funciona igual en CommonMark y en la especificación de GFM: no lo hace. Solo los cuadros de comentarios de issues/PR de GitHub.com convierten un salto de línea en un salto visible. Los archivos .md en GitHub siguen necesitando dos espacios finales, una barra invertida o una etiqueta <br> literal.
• Si no estás seguro de en qué dialecto escribir: CommonMark puro es el más portable, las extensiones de GFM son seguras para plataformas de estilo GitHub y las funciones exclusivas de GitHub.com deben tratarse como algo que puede romperse en otros lugares.
• El conversor Markdown a HTML de FormatArc admite las extensiones de GFM (tablas, tachado, listas de tareas, autoenlaces). También puedes usarlo para comprobar si tu Markdown depende de sintaxis exclusiva de GFM.

Respuesta corta: las tablas no forman parte de la especificación principal de CommonMark. Se definen en la especificación de GFM como una extensión, junto con el tachado, las listas de tareas, los autoenlaces extendidos y las reglas de HTML sin procesar no permitido.

Cómo se relacionan CommonMark y GFM: GFM se construye sobre CommonMark

CommonMark es el proyecto que tomó la gramática de Markdown, originalmente ambigua, y la volvió a especificar con precisión, con una batería de pruebas. El objetivo es eliminar las diferencias entre implementaciones para que cualquier analizador conforme produzca la misma salida. Como especificación, evita las extensiones de forma intencionada y solo define construcciones principales: encabezados, párrafos, listas, enlaces, imágenes, énfasis, código y citas.

GFM (GitHub Flavored Markdown) es el dialecto de Markdown que usa GitHub, y la propia especificación de GFM lo describe como un "superconjunto estricto" de CommonMark. En términos de la especificación, eso significa que:

• Cualquier documento CommonMark válido se renderiza de forma idéntica bajo un analizador de GFM.
• GFM solo añade un puñado de extensiones a CommonMark; no cambia la sintaxis principal.

La palabra "superconjunto" se aplica a lo que define la especificación de GFM. Una vez que tienes en cuenta la renderización real de GitHub.com, las implementaciones de cada biblioteca y la última revisión de CommonMark, aparecen casos límite. Este artículo mantiene separadas las "extensiones definidas por la especificación de GFM" y las "funciones que GitHub.com añade por su cuenta".

Tabla comparativa: CommonMark vs GFM

La clave está en las tres columnas. Las tablas, el tachado y las demás extensiones de GFM funcionan en cualquier analizador compatible con GFM, no solo en GitHub. Los avisos, los emoji y las notas al pie no están en la especificación de GFM, por lo que solo están garantizados en GitHub.com (o en plataformas que lo copian).

Tablas en CommonMark: la especificación principal no las define

La especificación de CommonMark excluye deliberadamente las tablas de la sintaxis principal. Las tablas de barras verticales y guiones (| col | col |) solo se definen en la especificación de GFM, donde la sección se titula literalmente "Tables (extension)". El propio GFM marca las tablas como una extensión, no como una construcción principal. La misma etiqueta "(extension)" se aplica al tachado, las listas de tareas, los autoenlaces extendidos y las reglas de HTML sin procesar no permitido.

Así, un renderizador solo de CommonMark (sin extensiones activadas) muestra | col | como un párrafo con barras verticales literales; un renderizador compatible con GFM analiza esa misma entrada y la convierte en una <table>. Por eso también las discusiones de larga duración en el foro de CommonMark y issues como commonmark-spec#393 siguen tratando las tablas como algo ajeno al alcance de la especificación principal.

Para comprobar si un renderizador concreto maneja las tablas como una extensión de GFM, pega una tabla de dos filas en Markdown a HTML y busca <table> en la salida.

Qué cambia realmente cuando conviertes a HTML

Un analizador solo de CommonMark y un analizador compatible con GFM producen HTML diferente a partir del mismo Markdown. Compara esta entrada:

| Product | Stock |
| --- | --- |
| Apple | 3 |

~~Sold out~~ — back in stock

- [x] Confirm restock
- [ ] Update price tags

Un analizador solo de CommonMark deja | Product | Stock | como un párrafo normal con barras verticales literales, mantiene las tildes de ~~Sold out~~ como texto en lugar de <del> y renderiza - [x] como un elemento de lista corriente. Un analizador compatible con GFM produce HTML con <table>, <del> e <input type="checkbox">.

Por eso, cuando "el Markdown parece roto", la causa suele ser una discrepancia de dialecto entre plataformas. Para comprobar si tu Markdown depende de las extensiones de GFM, pégalo en Markdown a HTML y observa la salida.

Las 5 extensiones que GFM añade a CommonMark

Tablas

Tablas construidas con barras verticales | y guiones -. CommonMark no tiene sintaxis de tablas, así que las tablas son una extensión de GFM, definida en la especificación de GFM en Tables (extension) (GFM spec §4.10). Un renderizador solo de CommonMark deja las barras verticales como texto. Para los marcadores de alineación (:--- / :---: / ---:), el escapado de barras dentro de las celdas y otros detalles, consulta Sintaxis de tablas en Markdown.

Tachado

~~texto a tachar~~ se convierte en un elemento <del>. Rodear texto con dobles tildes es una extensión de GFM y no forma parte de CommonMark: consulta la sección Strikethrough (extension) de la especificación de GFM (GFM spec §6.5).

Listas de tareas

Empieza un elemento de lista con - [ ] (sin marcar) o - [x] (marcado) y se renderiza como una casilla de verificación. La sintaxis se define en la sección Task list items (extension) de la especificación de GFM (GFM spec §5.3). En GitHub puedes hacer clic en la casilla dentro del cuerpo de un issue o de un PR para alternarla, pero ese comportamiento interactivo es una función de GitHub.com: un renderizador de HTML simple produce una casilla estática.

Autoenlaces extendidos

Escribe https://example.com directamente y se convierte en un enlace de forma automática. En CommonMark tienes que rodear una URL con corchetes angulares (<https://example.com>), pero GFM también detecta las URL sueltas y las enlaza. El comportamiento de las URL sueltas se especifica en la sección Autolinks (extension) de la especificación de GFM (GFM spec §6.9), que es distinta de los autoenlaces con corchetes angulares propios de CommonMark.

HTML sin procesar no permitido

Tanto CommonMark como GFM te permiten incrustar HTML sin procesar dentro de Markdown. La diferencia es que GFM deshabilita un pequeño conjunto de etiquetas (<script>, <iframe>, <style> y algunas otras) como "HTML sin procesar no permitido". Además de eso, GitHub.com ejecuta un saneador independiente y más estricto (que elimina atributos y mucho más). El conversor Markdown a HTML de FormatArc solo hace conversión de sintaxis, así que si conviertes entradas no confiables, sanea el HTML de salida por separado.

Dónde se define cada regla: las propias especificaciones

Si quieres verificar cualquiera de los puntos anteriores con la fuente, acude directamente a las especificaciones en lugar de a un resumen de terceros:

• La sintaxis principal la define la especificación de CommonMark (de John MacFarlane). Cubre encabezados, párrafos, listas, enlaces, imágenes, énfasis, código y citas, y explícitamente no define tablas, tachado, listas de tareas ni autoenlaces de URL sueltas.
• Las cuatro extensiones de GFM tratadas aquí tienen cada una su propia sección en la especificación de GitHub Flavored Markdown, y todas llevan la etiqueta "(extension)" en su título:
  • Tables (extension) — GFM spec §4.10
  • Task list items (extension) — GFM spec §5.3
  • Strikethrough (extension) — GFM spec §6.5
  • Autolinks (extension) — GFM spec §6.9

La etiqueta "(extension)" en cada título de GFM es la forma que tiene la propia especificación de marcarlas como añadidos a CommonMark y no como sintaxis principal. Las reglas de HTML sin procesar no permitido también se definen en la especificación de GFM, en la sección Disallowed Raw HTML (extension).

Funciones propias de GitHub.com, no de la especificación de GFM

Estas se presentan con frecuencia como "Markdown de GitHub" pero no están en la especificación de GFM. Trátalas como algo que solo funciona en GitHub.com (y en unos pocos servicios que lo imitan).

• Avisos: > [!NOTE] / > [!TIP] / > [!IMPORTANT] / > [!WARNING] / > [!CAUTION]. Se renderizan como recuadros de color.
• Atajos de emoji: la sintaxis :nombre: al estilo de :smile:. El Markdown estándar no tiene ningún concepto de emoji.
• @menciones / referencias a issues y PR / SHAs de commits: @usuario, #123 y los hash de commits se convierten en enlaces. Solo tienen sentido dentro del contexto de un repositorio.
• Diagramas Mermaid y fórmulas matemáticas: bloques de código ```mermaid y fórmulas $...$. Otra incorporación del flujo de renderizado de GitHub.com.
• Notas al pie: la sintaxis [^1]. GitHub.com las admite, pero no forman parte de la especificación de GFM. Algunas herramientas (como remark-gfm o el Goldmark de Hugo) activan las notas al pie junto con las extensiones al estilo de GFM, pero eso es una decisión de cada implementación.

Lleva un Markdown que use estas funciones a un contexto que no sea GitHub (un blog en el que pegaste un README, una herramienta de documentación) y normalmente aparece como texto plano. Trátalas como sintaxis exclusiva de GitHub.com.

Los saltos de línea (saltos de línea forzados) funcionan de forma diferente

Este es un punto de confusión habitual. Tanto en CommonMark como en la especificación de GFM, un único salto de línea dentro de un párrafo (un salto de línea suave) no se convierte en <br>: las líneas se unen en un solo párrafo. Para forzar un <br>, pones dos espacios finales, una barra invertida final \ o una etiqueta <br> literal. Eso es idéntico en CommonMark y en GFM.

La excepción son los cuadros de comentarios de issues/PR/discusiones de GitHub.com, que están configurados para convertir un único salto de línea directamente en un <br>. En el mismo GitHub, los archivos .md (READMEs, documentación) siguen el comportamiento estándar de CommonMark/GFM y aún necesitan dos espacios o \. "Obtuve saltos de línea en un comentario de GitHub pero no en mi README" es exactamente esto.

Qué plataformas y herramientas usan cada dialecto

Con más precisión: a cuál de "CommonMark puro", "CommonMark + extensiones de GFM" o "su propio dialecto" se acerca más cada herramienta. Una lista representativa:

"Compatible con GFM" no significa necesariamente que la herramienta también admita los avisos o los emoji de GitHub.com. A la inversa, una herramienta "solo CommonMark" normalmente puede obtener las extensiones de GFM añadiendo un plugin. En caso de duda, consulta la documentación de la biblioteca o el servicio que uses para saber "qué extensiones están activadas".

Cómo comprobar si tu entorno admite GFM

Puedes obtener una respuesta aproximada sin ninguna investigación a fondo:

• Escribe una tabla (| col |), un tachado (~~texto~~) y una lista de tareas (- [ ]) y observa si cada uno se renderiza. Si lo hacen, las extensiones de GFM están activadas.
• Si usas una biblioteca, revisa su configuración. marked necesita gfm: true, remark necesita el plugin remark-gfm y markdown-it activa las tablas y el tachado de GFM de forma predeterminada.
• Para los generadores de sitios estáticos, revisa el archivo de configuración. Hugo tiene markup.goldmark.extensions, Astro tiene markdown.remarkPlugins (busca remark-gfm), y así sucesivamente.

Si solo quieres saber si un archivo de Markdown concreto depende de las extensiones de GFM, pégalo en Markdown a HTML y observa si las tablas y el tachado se convierten en HTML.

¿En qué dialecto deberías escribir?

• CommonMark puro es el más portable. Se renderiza tal como pretendías en prácticamente todos los renderizadores.
• Si tu objetivo son GitHub o plataformas similares a GitHub (GitLab, la mayoría de las herramientas de documentación), las extensiones de GFM (tablas, tachado, listas de tareas, autoenlaces) están bien. Esa es la opción predeterminada práctica.
• Los avisos ([!NOTE], etc.), los atajos de emoji, las @menciones, Mermaid y las notas al pie deben usarse "asumiendo que se rompen fuera de GitHub.com". Resultan prácticos en un README, pero pégalo en un blog y se convierte en texto plano.
• Si la portabilidad importa, evita mezclar HTML sin procesar. Tanto en CommonMark como en GFM, los documentos con HTML sin procesar están sujetos al saneado y al comportamiento específico de cada renderizador.

¿Qué dialecto usa el conversor de FormatArc?

El conversor Markdown a HTML de FormatArc ejecuta marked con gfm: true internamente. Por lo tanto:

• Las extensiones de la especificación de GFM (tablas, tachado, listas de tareas, autoenlaces extendidos) se convierten directamente a HTML.
• Un salto de línea suave dentro de un párrafo sigue el comportamiento breaks: false: no se convierte en <br>. Igual que CommonMark/la especificación de GFM, y distinto del comportamiento del cuadro de comentarios de GitHub.com.
• Las funciones exclusivas de GitHub.com (avisos como [!NOTE], atajos de emoji, @menciones, Mermaid, notas al pie) no son compatibles, porque no forman parte de la especificación de GFM.

La herramienta inversa, HTML a Markdown, produce un Markdown al estilo de GFM que incluye tablas y tachado. Ambas se ejecutan por completo en el navegador, sin registro y sin subida de archivos, así que pegar un documento interno no publicado no lo envía a ninguna parte.

Para guías de conversión paso a paso, consulta Cómo convertir Markdown a HTML y, para el sentido inverso, Cómo convertir HTML a Markdown.

Preguntas frecuentes

¿Debería escribir Markdown en CommonMark o en GFM?

CommonMark puro es el más portable. Si tu objetivo son GitHub o plataformas similares a GitHub, las extensiones de GFM (tablas, tachado, listas de tareas, autoenlaces) están bien. Usa las funciones exclusivas de GitHub.com como [!NOTE] asumiendo que se rompen fuera de GitHub.

¿Tiene CommonMark sintaxis de tablas?

No. Las tablas son una extensión de GFM y no están en la especificación de CommonMark. Un renderizador solo de CommonMark muestra | col | como texto plano con barras verticales literales. Para más detalles sobre cómo escribir tablas, consulta Sintaxis de tablas en Markdown.

¿Funcionan los avisos [!NOTE] de GitHub en otras herramientas?

Por lo general, solo en GitHub.com (y en unos pocos servicios que lo imitan). La especificación de GFM no tiene sintaxis de avisos, así que otros renderizadores muestran > [!NOTE] como texto dentro de una cita.

¿Son Obsidian y Notion compatibles con GFM?

No del todo. Obsidian se basa en CommonMark, admite tablas y listas de tareas de GFM y añade su propia sintaxis como [[wikilinks]]. Notion tiene su propio dialecto; su exportación a Markdown se parece a GFM, pero la sintaxis dentro del editor es específica de Notion. Consulta la documentación de cada herramienta para conocer la sintaxis admitida.

¿Con qué dialecto convierte FormatArc?

Parecido a GFM. Markdown a HTML ejecuta marked con gfm: true, así que admite tablas, tachado, listas de tareas y autoenlaces. Los saltos de línea suaves no se convierten en <br> (igual que CommonMark/la especificación de GFM). Las funciones exclusivas de GitHub.com (avisos, emoji, menciones, Mermaid, notas al pie) no son compatibles.

Artículos relacionados

• Cómo convertir Markdown a HTML: los pasos concretos para convertir Markdown a HTML, incluidas las tablas y las listas de tareas de GFM.
• Sintaxis de tablas en Markdown: alineación, escapado, ejemplos para copiar y pegar: la alineación de tablas de GFM, el escapado de barras verticales y el manejo de saltos de línea en detalle.
• Chuleta de tablas de GFM: referencia de una sola página sobre alineación, barras verticales escapadas y resultado renderizado en GitHub / GitLab / Obsidian / Notion.
• Cómo convertir HTML a Markdown: convertir HTML de páginas web o de exportaciones de Notion en Markdown al estilo de GFM.

Conclusión

CommonMark es la especificación estándar de Markdown; GFM es un dialecto que se construye sobre ella con cinco extensiones (tablas, tachado, listas de tareas, autoenlaces extendidos, HTML sin procesar no permitido). Los avisos, los emoji, las @menciones, Mermaid y las notas al pie que ves en GitHub.com se sitúan en otra capa más (la propia de GitHub.com) y, por lo general, no funcionan fuera de GitHub.

Si no estás seguro de en qué dialecto escribir: CommonMark para la máxima portabilidad, las extensiones de GFM para plataformas de estilo GitHub y las funciones exclusivas de GitHub.com asumiendo que se rompen en otros lugares. Cuando quieras comprobar si tu Markdown depende de las extensiones de GFM, o simplemente convertir Markdown a HTML, usa Markdown a HTML: se ejecuta por completo en el navegador, sin registro y sin subida de archivos.