Por qué tu Markdown se ve distinto en GitHub, Notion y tu editor

Publicado el 20 de julio de 2026

Escribes una tabla, la ves perfecta en tu editor, la pegas en otra aplicación y aparece como un amasijo de barras verticales. No has escrito mal el Markdown. El problema es que la aplicación de destino habla un dialecto distinto al de tu editor.

No existe un solo Markdown

Cuando John Gruber publicó Markdown en 2004, lo acompañó de un script en Perl y de una descripción en prosa de cómo debía comportarse. Esa descripción dejaba muchos casos sin definir, y ahí empezó el problema.

¿Qué pasa si anidas una lista dentro de una cita? ¿Y si pones negrita a mitad de una palabra? ¿Cuántos espacios necesita una sublista? La especificación original no lo aclaraba, así que cada persona que escribió un procesador tomó sus propias decisiones. El resultado es que hoy conviven decenas de implementaciones que coinciden en lo básico y divergen en cuanto rascas un poco.

Por eso el mismo archivo se ve distinto según dónde lo abras. No es un fallo tuyo ni un fallo de la aplicación, es la consecuencia de que Markdown creció sin un estándar durante casi una década.

CommonMark, el intento de poner orden

CommonMark es una especificación que nació precisamente para cerrar esos huecos. Define con precisión qué debe hacer un procesador ante cada caso ambiguo, y viene acompañada de una batería enorme de pruebas para que cualquier implementación pueda verificar que cumple.

Lo importante para ti es lo que CommonMark deja fuera. La especificación cubre el Markdown esencial y poco más:

Encabezados, párrafos y saltos de línea
Énfasis con asteriscos o guiones bajos
Listas ordenadas y sin ordenar
Enlaces e imágenes
Citas, bloques de código y líneas horizontales
HTML embebido

Fíjate en lo que no está en esa lista: no hay tablas, no hay tachado, no hay listas de tareas y no hay notas al pie. Todo eso son extensiones que cada aplicación añade por su cuenta, y son justo los elementos que más problemas de compatibilidad te van a dar.

Puedes repasar qué entra en el núcleo del lenguaje en la página de sintaxis básica y qué pertenece al terreno de las extensiones en sintaxis extendida.

GitHub Flavored Markdown, el dialecto que todos imitan

GitHub Flavored Markdown, que verás abreviado como GFM, es una capa que se apoya en CommonMark y le añade lo que faltaba para documentar proyectos de software.

Ese añadido incluye las tablas, el tachado con dos virgulillas, las listas de tareas con casillas marcables y la detección automática de enlaces. Como GitHub se convirtió en el sitio donde vive la documentación técnica, su dialecto acabó siendo el de facto: muchísimas herramientas dicen soportar Markdown cuando en realidad soportan algo parecido a GFM.

Ese "parecido" es la clave. Una aplicación puede implementar las tablas de GFM pero no sus listas de tareas, o soportar ambas pero sanear el HTML de otra manera. Tienes el detalle de este dialecto en la guía de Markdown en GitHub.

Los cinco puntos donde tu texto se rompe

En la práctica, casi todos los desajustes que te vas a encontrar se concentran en un puñado de elementos. Estos son los sospechosos habituales.

Los saltos de línea

Es la diferencia que más desconcierta. En el Markdown clásico, pulsar Intro una vez no crea un salto de línea: para forzarlo hay que terminar la línea con dos espacios o usar una barra invertida.

Muchas aplicaciones de mensajería y de notas decidieron que eso era poco intuitivo y convierten el salto simple en un salto real. Así que el mismo texto queda compacto en un sitio y separado en otro. Lo tienes desglosado en el consejo sobre saltos de línea.

Las tablas

No están en CommonMark. Si la aplicación de destino solo implementa el núcleo, tu tabla se queda tal cual, en texto plano con barras y guiones a la vista.

Cuando sí las soporta, quedan por medio los detalles: si admite alineación por columnas, si tolera que las barras exteriores falten, si deja meter saltos de línea dentro de una celda. Sobre esto último, la respuesta corta es que casi nunca se puede, y la larga está en formatear tablas.

El resaltado y el subrayado

El resaltado con dos signos igual no forma parte ni de CommonMark ni de GFM. Funciona en aplicaciones de notas como Obsidian, Typora, Logseq o iA Writer, y se queda en texto literal en plataformas de código, como puedes ver en resaltar texto.

Con el subrayado pasa algo parecido y más radical: Markdown directamente no tiene sintaxis para subrayar, porque el subrayado en la web significa enlace. La única vía es el HTML, y ahí entramos en el siguiente problema. Lo explica subrayar texto.

El HTML embebido

Markdown permite escribir HTML directamente, y durante años esa fue la vía de escape para todo lo que la sintaxis no cubría: centrar una imagen, crear un desplegable, cambiar un color.

El detalle es que esa vía de escape depende por completo de la aplicación. Una plataforma que publica contenido de terceros va a filtrar el HTML por seguridad, porque aceptar etiquetas arbitrarias es la puerta de entrada a ataques de inyección. Así que tu bloque con estilos puede funcionar en tu editor local y desaparecer al publicarlo. Es lo que condiciona técnicas como centrar imágenes o crear desplegables.

Los bloques de código anidados

Si documentas Markdown escribiendo sobre Markdown, tarde o temprano necesitas meter un bloque de código dentro de otro, y las tres comillas invertidas se pelean entre sí.

La solución está estandarizada, aunque casi nadie la conoce: el bloque exterior tiene que abrirse con más comillas invertidas que el interior. Con cuatro fuera y tres dentro funciona.

```js
console.log('esto queda dentro del bloque exterior')
```

Las extensiones que cada plataforma añade por su cuenta

Por encima de CommonMark y de GFM, muchas plataformas incorporan su propia sintaxis para necesidades concretas. Son cómodas y merece la pena usarlas, siempre que tengas presente que fuera de su casa no significan nada.

Dos ejemplos habituales en repositorios de código son las notas al pie y los avisos destacados. Las notas al pie usan una referencia entre corchetes con acento circunflejo, y los avisos se escriben como una cita que empieza por una etiqueta entre corchetes:

Una afirmacion que necesita matiz.[^1]

[^1]: El matiz va aqui abajo.

> [!NOTE]
> Un aviso destacado.

Ambas están consolidadas en el ecosistema de GitHub, pero ninguna pertenece al núcleo del lenguaje. Pegadas en una aplicación que no las conozca, la nota al pie se queda como texto entre corchetes y el aviso se convierte en una cita normal con un [!NOTE] colgando dentro. Tienes el detalle en crear notas al pie y en mostrar advertencias.

La regla práctica es sencilla: cuanto más vistosa y específica es una sintaxis, menos probable es que sea estándar.

Cómo escribir Markdown que sobreviva al viaje

Si tu texto va a acabar en varios sitios, la estrategia que mejor funciona es escribir para el mínimo común denominador y añadir extras solo cuando sepas dónde se va a publicar.

En la práctica se traduce en unas pocas costumbres:

Quédate en el núcleo de CommonMark siempre que puedas: encabezados, listas, énfasis, enlaces, citas y bloques de código funcionan en todas partes.
Trata las tablas, el tachado y las listas de tareas como elementos de riesgo. Úsalos, pero sabiendo que son extensiones.
Evita el HTML si el destino es una plataforma pública. Si lo necesitas de verdad, comprueba antes qué etiquetas deja pasar.
Deja siempre una línea en blanco antes y después de las listas, las tablas y los bloques de código. Es la causa número uno de listas que no se renderizan.
Usa un solo estilo de marcado para cada cosa. Si empiezas con asteriscos para el énfasis, no mezcles guiones bajos.
No dependas de los saltos de línea sueltos. Si necesitas separación real, usa un párrafo nuevo.

Cómo saber qué dialecto usa una aplicación

Antes de pelearte con un texto que no se ve bien, merece la pena averiguar contra qué estás escribiendo. Hay tres formas rápidas.

La primera es la documentación de la propia herramienta, que suele indicar si sigue CommonMark, GFM o una variante propia. La segunda es una prueba directa: escribe una tabla, un tachado y una casilla de tarea, y mira cuáles sobreviven. Con esos tres elementos sitúas el dialecto en cuestión de segundos.

La tercera es fijarse en qué motor hay debajo. Muchas aplicaciones usan procesadores conocidos y heredan su comportamiento, así que identificar el motor te dice de antemano qué esperar. Tienes un repaso de los principales en la página de parsers de Markdown.

Ten en cuenta también que el destino condiciona el dialecto. No es lo mismo escribir para un repositorio, para una aplicación de notas como Obsidian o Notion, o para un foro como Reddit, donde el conjunto de elementos soportados es más reducido. Consulta siempre la documentación oficial de cada plataforma para los detalles concretos, porque cambian con el tiempo.

Cuando necesitas control total

Si lo que te importa es que el resultado sea exactamente el mismo en todas partes, el camino no es pelear con los dialectos, sino convertir el Markdown a un formato final antes de distribuirlo.

Ahí es donde entran los conversores: pasando tu texto a HTML, a PDF o a DOCX fijas el resultado y dejas de depender de cómo interprete cada aplicación tu archivo original. Es la estrategia habitual cuando el documento va a manos de otras personas y no puedes controlar con qué lo van a abrir.