GitHub Flavored Markdown vs CommonMark: a cuál deberías apuntar tu conversión
Elige el dialecto de Markdown equivocado para tu destino y la conversión técnicamente tiene éxito mientras el resultado se renderiza mal en silencio: las tablas se convierten en texto literal, el tachado muestra sus tildes, las listas de casillas pierden sus cajas. La solución no cuesta nada, pero solo si eliges antes de convertir.
Esta guía explica qué especifica realmente CommonMark, qué añade GitHub Flavored Markdown encima, qué plataformas hablan cada variante y cómo se traduce la elección en la práctica cuando un conversor se interpone entre tus borradores de Word y su destino final de publicación.
CommonMark: una especificación para el núcleo de Markdown
El Markdown clásico era un script de Perl con una descripción en prosa, y en la década de 2010 decenas de implementaciones discrepaban en casos básicos: si una lista continúa después de un párrafo sangrado, qué cuenta como énfasis a través de saltos de línea, cuándo un número seguido de un punto es una lista. El mismo archivo se renderizaba de forma distinta en casi todas partes.
CommonMark respondió con una especificación formal: una gramática sin ambigüedades para la sintaxis central de Markdown, cientos de ejemplos de prueba con una única renderización correcta cada uno e implementaciones de referencia con las que contrastar. John MacFarlane, que también desarrolla pandoc, estuvo entre sus autores, y la especificación se afianzó rápido.
Hoy CommonMark es la capa base sobre la que se construye casi todo. Deliberadamente no incluye tablas ni tachado; solo define los cimientos sobre los que se asientan esas funciones, que es exactamente por lo que hizo falta una segunda capa de extensiones.
Lo que GFM añade encima
GitHub Flavored Markdown, especificado públicamente en 2017, es un superconjunto estricto de CommonMark. Sus adiciones son cinco: tablas escritas con barras verticales, tachado con tildes dobles, elementos de lista de tareas con casillas, enlace automático de URL desnudas y un filtro que bloquea la ejecución de ciertas etiquetas HTML en bruto.
Cada adición apunta a algo que los desarrolladores ya estaban escribiendo. Las tablas con barras cubren matrices de dependencias y de pruebas; las listas de tareas convierten un README en una checklist; los autoenlaces evitan envolver cada URL en corchetes angulares. El filtro de HTML es una medida de seguridad que elimina las etiquetas que hacen peligroso el HTML incrustado en un sitio donde cualquiera puede editar.
GitHub renderiza Markdown a través de cmark-gfm, un fork de la implementación de referencia de CommonMark con estas extensiones integradas. GitLab y Gitea siguen la misma forma general, por lo que GFM se comporta de manera consistente en las grandes forjas de código en lugar de cambiar de un sitio a otro.
Dónde vive cada variante
GFM está en casa en GitHub, obviamente, y en las herramientas de sitios estáticos que lo adoptan por defecto: Hugo renderiza a través de un motor configurado para GFM desde el principio, y MkDocs habilita tablas de fábrica. Obsidian acepta los tres constructos característicos —tablas con barras, tachado y listas de tareas— y añade sus propias funciones de dialecto encima.
Los parsers estrictos de CommonMark viven en bibliotecas y motores de blogs que deliberadamente prefieren un núcleo pequeño y predecible. El Markdown por defecto de pandoc es un tercer dialecto, un gran superconjunto con tablas de cuadrícula, sintaxis de citas y otras extensiones que GitHub no renderiza.
Nada de esto hace que una variante sea mejor que la otra. La cuestión nunca es qué dialecto gana en abstracto, sino qué dialecto renderiza realmente tu destino, y si el archivo que estás a punto de producir se mantiene dentro de ese límite.
Por qué a los conversores les importa la diferencia
Un conversor no solo traduce sintaxis, elige un dialecto que emitir. Las tablas son donde la elección se ve más. Si el destino es GitHub y el dialecto de salida admite tablas con barras, una tabla simple llega como tabla. Si no, la misma tabla puede retroceder a una sintaxis que el destino ignora, y los lectores ven filas de texto plano con barras verticales dentro.
El tachado y las casillas de las listas de tareas fallan del mismo modo, solo que más discreto: tildes que quedan visibles en el texto, corchetes de casilla que se renderizan literalmente. El documento no está dañado en ningún sentido real, simplemente habla un idioma que el renderizador del lector no conoce.
Por eso el formato de origen importa menos de lo que la gente cree. Pandoc analiza la entrada, ya sea docx o CSV, en un modelo de documento abstracto, y la decisión del dialecto ocurre al escribir la salida. Un reader, muchos writers, y el writer es lo que tú controlas.
Elegir según el destino
Para cualquier cosa que aterrice en una forja de código o en una bóveda, elige GFM: los pull requests de GitHub, las wikis de GitLab, las notas de Obsidian y los sitios de Hugo renderizan sus constructos. Para un motor de blog o biblioteca que anuncia CommonMark estricto, elige CommonMark puro y espera que las tablas necesiten un respaldo de HTML o de extensión.
Cuando no conoces el destino, GFM es el valor por defecto más seguro. Sus cuatro adiciones visibles son las extensiones más ampliamente soportadas del mundo Markdown, y las plataformas que omiten alguna suelen degradar con elegancia en lugar de mostrar sintaxis en bruto.
El único error que vale la pena evitar es asumir que un superconjunto siempre es seguro. Un archivo escrito en Markdown de pandoc con tablas de cuadrícula o sintaxis de citas se ve bien en pandoc y se rompe en GitHub. Emitir el dialecto del destino supera a emitir uno más rico que el destino no puede analizar.
Qué cambia el interruptor GFM en la conversión
El conversor de este sitio expone la elección como un único interruptor. Con GFM activado, la salida Markdown usa tablas con barras, mantiene intactas las sintaxis de tachado y listas de tareas, y evita constructos que GitHub no renderiza, como etiquetas HTML de imagen en bruto o atributos de ancho adjuntos a enlaces.
Sin él, la salida sigue el sabor propio de Markdown de pandoc: sigue siendo perfectamente válida, sigue siendo legible, pero las tablas complejas pueden salir en dialectos que GitHub ignora, y las funciones más allá del núcleo de CommonMark no tienen garantizado aterrizar en sus formas GFM familiares al otro lado.
El interruptor también tiene una interacción silenciosa que conviene conocer: para entradas CSV y TSV, el resultado es un documento de tabla, y el modo GFM es lo que mantiene esa tabla en la sintaxis de barras que GitHub realmente renderiza, en lugar de una variante que ignora.
El caso límite de los saltos de línea
Los saltos de línea son la diferencia que sobrevive a cualquier otra elección. En CommonMark, un solo salto de línea dentro de un párrafo es un salto suave, renderizado como un espacio, y necesitas dos espacios finales o una barra invertida para un salto duro. GFM mantiene esa regla para los archivos.
La realidad es más caótica: los comentarios y cuerpos de issues de GitHub tratan los saltos de línea simples como saltos visibles, y Obsidian hace lo mismo por defecto a menos que actives los saltos estrictos en los ajustes. Así, un párrafo cortado a mitad de frase se renderiza de una manera en GitHub y de otra en el README que tiene al lado.
La regla práctica: escribe los párrafos como líneas largas únicas cuando la salida sea CommonMark o GFM, y apóyate en el salto-de-línea-como-corte solo donde la plataforma te ha dicho que funciona así. Todo lo demás sobre la elección de dialecto se puede arreglar después; los saltos de línea son el problema que se esconde a plena vista.