¿Tu tabla Markdown no se muestra o sale rota? Arréglala por síntoma

Empieza aquí — el orden de diagnóstico

Cuando una tabla Markdown se rompe, ningún parser te dice por qué. Si la tabla no se reconoce, se muestra en silencio como un párrafo normal. Si un límite de celda se interpreta mal, obtienes columnas desplazadas sin ningún aviso. Sin mensaje de error, la única salida es descartar causas en orden.

Hay cinco cosas que comprobar, ordenadas por lo fiable que es cada una a la hora de romper tablas y por lo barato que resulta verificarlas:

1. ¿La fila separadora tiene el mismo número de columnas que la fila de cabecera? (Un desajuste es la única condición de sintaxis que impide reconocer la tabla a nivel de especificación)
2. ¿Hay una barra vertical | sin escapar dentro de alguna celda, incluso dentro de un código entre backticks?
3. ¿Hay una línea en blanco antes de la tabla?
4. ¿Tu renderizador soporta tablas GFM?
5. ¿Es un problema de entorno y no de sintaxis (tipo de celda en Jupyter, el CSS de la plataforma)?

La forma más rápida de partir el problema en dos es pegar una tabla mínima:

| A | B |
| --- | --- |
| 1 | 2 |

Si estas tres líneas no se renderizan como tabla, el problema es tu renderizador o tu entorno, no tu tabla (salta a la segunda mitad del síntoma 1). Si sí se renderizan, el problema está en cómo escribiste tu tabla — repasa desde el síntoma 1 en adelante.

Para ver cómo un parser GFM interpreta realmente tu tabla, pégala en Markdown a HTML. Muestra el HTML que produce un parser GFM basado en marked, todo en tu navegador: si ves una etiqueta <table> en la salida, el parseo funcionó. Nada de lo que pegas se sube a ningún sitio. Eso sí, esto verifica el parseo de la familia GFM; no reproduce exactamente Notion, la wiki de tu empresa ni la plataforma donde publicas.

Este artículo se centra solo en resolver problemas. Si quieres aprender la sintaxis desde cero, consulta la sintaxis de tablas en Markdown.

Síntoma 1: la tabla se muestra como texto plano

Tus líneas separadas por barras aparecen como un párrafo corriente. Eso significa que el parser nunca las reconoció como tabla.

La fila separadora y la cabecera tienen distinto número de columnas

Esta es la única condición de sintaxis que anula de forma fiable el reconocimiento de la tabla. La especificación de GFM es explícita: si el número de columnas de la fila separadora no coincide con la cabecera, el bloque no se trata como tabla. No hay error — simplemente cae a párrafo.

Aquí hay un ejemplo roto. La cabecera tiene tres columnas, pero la fila separadora solo dos:

| Nombre | Correo | Rol |
| --- | --- |
| Mika | mika@example.com | admin |

Iguala la fila separadora a la cabecera y se renderiza:

| Nombre | Correo | Rol |
| --- | --- | --- |
| Mika | mika@example.com | admin |

Solo necesitas contar dos líneas: la cabecera y la separadora. Las filas de datos con celdas de más o de menos no rompen el reconocimiento (lo vemos en el síntoma 2).

Falta una línea en blanco antes de la tabla

Algunos parsers se niegan a reconocer una tabla que empieza justo después de un párrafo sin línea en blanco de por medio. En mis pruebas (2026-06-12), el renderizador de producción de GitHub (vía Markdown API), marked 18.0.1 y remark-gfm 4.0.1 reconocieron la tabla sin línea en blanco — pero otras implementaciones y plataformas no lo hacen. Añadir una línea en blanco es la corrección más barata que puedes probar, así que compruébala justo después de las columnas.

"Necesitas al menos tres guiones" es casi un mito

Muchos artículos bien posicionados afirman que cada columna de la fila separadora requiere tres o más guiones. La especificación de GFM no fija ningún mínimo. Verifiqué que un solo guion por columna (| - | - |) se renderiza como tabla en el renderizador de producción de GitHub, en marked 18.0.1 y en remark-gfm 4.0.1.

Lo confuso es el desacuerdo a tres bandas: la documentación de GitHub dice tres o más, la especificación no fija regla alguna y la implementación acepta uno. Trata los tres guiones como una convención de legibilidad. Jugar con el número de guiones para arreglar una tabla rota es perder el tiempo — revisa primero las columnas y las líneas en blanco. La matriz completa de pruebas con cuatro parsers está en la sintaxis de tablas en Markdown.

La única excepción real es combinar barras exteriores omitidas con un solo guion, que cubrimos en el síntoma 4.

Tu renderizador no soporta tablas GFM

Las tablas no son parte del núcleo de Markdown. El CommonMark puro no define ninguna sintaxis de tablas — las tablas son una extensión de GFM. Un renderizador CommonMark estricto sin extensiones nunca renderizará tu tabla, por correcta que esté. El contexto completo está en CommonMark vs GFM.

Los problemas de entorno ajenos a la sintaxis también van aquí. En Jupyter Notebook, por ejemplo, una celda que sigue siendo de tipo Code no renderiza Markdown en absoluto. Si la prueba de la tabla mínima falló, busca en esta familia de causas.

Síntoma 2: las columnas se desplazan o una celda se parte en dos

La tabla se renderiza, pero las columnas caen donde no deben, o una celda se convierte en dos.

Una barra vertical sin escapar dentro de una celda

La barra | es el separador de columnas, así que escribirla como contenido parte la columna ahí mismo. La siguiente tabla pretendía mostrar "cmd1 | cmd2" como ejemplo de comando en la primera columna — en su lugar, "cmd1" y "cmd2" caen en celdas distintas, y "encadenado con pipe", que excede las dos columnas de la cabecera, se descarta en silencio:

| Comando | Significado |
| --- | --- |
| cmd1 | cmd2 | encadenado con pipe |

Sustituye la barra por \| (escape con barra invertida) o | (entidad HTML numérica) y se queda en una sola celda:

| Comando | Significado |
| --- | --- |
| cmd1 \| cmd2 | encadenado con pipe |

Los códigos entre backticks tampoco protegen las barras

Aunque parezca contraintuitivo, envolver la barra en backticks no ayuda. La división de celdas ocurre antes de que se interpreten los elementos en línea:

| Comando | Significado |
| --- | --- |
| `a | b` | pretendía ser código |

Esta fila se parte en las dos celdas `a y b` tanto en el renderizador de producción de GitHub como en marked y remark-gfm (probado el 2026-06-12). Los backticks nunca se emparejan y se muestran como caracteres literales.

La solución es usar el escape con barra invertida también dentro del código:

• Escribe `a \| b` — el \| funciona también dentro de los backticks. Verificado: se renderiza como el código a | b en GitHub, marked y remark-gfm
• | no funciona dentro de un código entre backticks. Ahí las referencias de caracteres no se expanden, así que los seis caracteres | aparecen tal cual
• En resumen: en texto normal de celda funcionan tanto \| como |; dentro de backticks solo funciona \|

Filas de datos con celdas de más o de menos se ven como desplazamiento

Una fila de datos cuyo número de celdas difiere de la cabecera no rompe la tabla — aparece como un desfase visual. En mis pruebas, las filas con celdas de menos se rellenan con celdas vacías, y las celdas sobrantes se descartan en silencio. Si el valor de la última columna parece desaparecer, busca una barra extra (una columna de más) en esa fila.

Escapar barras a mano y vigilar el número de columnas en una tabla grande agota a cualquiera. Si los datos viven en CSV o en una hoja de cálculo, pégalos en CSV a Markdown y obtendrás una tabla con columnas coherentes y las barras ya escapadas.

Síntoma 3: un salto de línea dentro de una celda destroza la tabla

La sintaxis de tablas Markdown no tiene salto de línea dentro de celda. Pulsar Enter dentro de una celda inicia una nueva fila de la tabla — o termina la tabla por completo.

La solución alternativa es una etiqueta HTML <br> directamente en la celda:

| Elemento | Notas |
| --- | --- |
| Ajuste A | primera línea<br>segunda línea |

Ten en cuenta que <br> no es sintaxis de Markdown — es un recurso de HTML crudo. Los renderizadores que desactivan o sanean el HTML lo ignorarán. En esos entornos, lo realista es dividir la frase o dividir la fila. La referencia completa de escapes y saltos de línea está en la chuleta de tablas GFM.

Síntoma 4: funciona en GitHub, se rompe en otro sitio

El mismo Markdown puede parsearse distinto en parsers distintos. La divergencia más clara que medí es la combinación de barras exteriores omitidas con un solo guion:

A | B
- | -
1 | 2

La línea separadora empieza con - (guion más espacio), así que los parsers discrepan sobre si es un marcador de lista. GitHub y remark-gfm la leen como lista y no renderizan tabla; marked sí renderiza una tabla (probado el 2026-06-12). Si omites las barras exteriores, usa al menos dos guiones — o conserva las barras exteriores y el problema nunca aparece.

"En mi vista previa funciona pero se rompe donde publico" casi siempre se reduce a una diferencia de parser como esta, o a la falta de soporte GFM del síntoma 1. Para concretar qué acepta tu plataforma de destino, combina la prueba de la tabla mínima con la comprobación del HTML de salida en Markdown a HTML. Para las diferencias plataforma a plataforma — Notion ignorando los dos puntos de alineación y el <br>, por ejemplo — consulta la tabla de plataformas en la sintaxis de tablas en Markdown.

Cuando reconstruir gana a reparar

Contar barras en una tabla rota de 30 filas rara vez merece la pena. Si los datos de origen existen como CSV, Excel o una hoja de cálculo, regenerar la tabla lleva menos de un minuto:

1. Copia los datos como CSV (también vale un rango copiado de Excel o Google Sheets)
2. Pégalo en CSV a Markdown
3. Copia la tabla Markdown generada sobre la tabla rota

La coherencia de columnas, el escape de barras y la fila separadora corren a cargo de la herramienta. La conversión se ejecuta por completo en tu navegador y los datos no se envían a ninguna parte, algo que importa cuando la tabla contiene datos internos. Para el paso a paso completo, consulta cómo convertir CSV en una tabla Markdown; para convertir la tabla arreglada en HTML, la guía de Markdown a HTML.

Cierre — quédate con el orden

Cuando una tabla se muestra como texto plano: revisa el número de columnas de cabecera y separadora, luego la línea en blanco antes de la tabla, y después si el renderizador soporta GFM. Cuando las columnas se desplazan: busca barras sin escapar en las celdas (escápalas con \|, también dentro de backticks) y filas de datos con columnas de más. El número de guiones no es el culpable, salvo en el caso límite de las barras exteriores omitidas.

Para diagnosticar, comprobar el HTML de salida en Markdown a HTML es el atajo; para reparar, regenerar con CSV a Markdown es el camino seguro. Ambos se ejecutan por completo en tu navegador.

Artículos relacionados

• Sintaxis de tablas en Markdown — fundamentos de sintaxis y la matriz de pruebas con cuatro parsers
• Chuleta de tablas GFM — referencia de alineación, escapes y saltos de línea
• CommonMark vs GFM — por qué las tablas son una extensión
• Cómo convertir CSV en una tabla Markdown — la ruta de regeneración en detalle
• Guía de Markdown a HTML — cómo funciona la conversión detrás de la comprobación de renderizado