Sintaxis de tablas en Markdown: barras, guiones y alineación

Respuesta rápida

Las tablas en Markdown usan barras verticales | y guiones -. No se necesita nada más.

| Name | Email | Role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |

Si escribir barras a mano no te parece un buen plan, pega tu CSV en CSV a Markdown y obtén una tabla con formato al instante. El resto de este artículo explica la sintaxis en detalle.

Sintaxis básica — barras y guiones

Una tabla Markdown tiene tres partes:

1. Fila de encabezado — nombres de columna separados por barras |
2. Fila separadora — guiones - (por convención, tres por columna), que separan el encabezado de los datos
3. Filas de datos — valores de celda separados por barras

| Item | Value |
| --- | --- |
| CPU | Apple M4 |
| RAM | 16 GB |

Las barras al inicio y al final son opcionales, pero se recomiendan para mayor legibilidad. No hace falta alinear el ancho de las columnas en el código fuente; el renderizador se encarga de eso.

Anatomía de la barra y la fila separadora

La barra vertical | separa las columnas. La fila separadora — también llamada separador de encabezado o fila de guiones — se construye con guiones - y le indica al renderizador dónde termina el encabezado y dónde empiezan los datos.

Algunas reglas que conviene conocer sobre las barras y los guiones:

• Tres guiones por columna (---) es la convención, no una regla del analizador. La especificación GFM no fija un mínimo, y -- o incluso un solo - se renderiza como tabla en los renderizadores GFM (verificado con marked 18.0.5 y remark-gfm 4.0.1). Usa tres guiones por legibilidad, no porque menos vayan a fallar
• Lo que realmente rompe una tabla es una fila separadora cuyo número de columnas difiere de la fila de encabezado. La especificación GFM es explícita: si los números no coinciden, la tabla simplemente no se reconoce. Más abajo se mide caso por caso
• Las barras al inicio y al final de la fila son opcionales, pero se recomiendan para mayor legibilidad. | A | B | y A | B se renderizan igual — con una excepción medida: si además dejas un solo guion en la fila separadora, GitHub y remark-gfm leen la línea como una lista y la tabla no aparece
• Los dos puntos de alineación (:---, :---:, ---:) solo van en la fila separadora, nunca en las filas de datos
• La fila de encabezado es obligatoria en GFM. La especificación principal de CommonMark no incluye tablas en absoluto, así que las tablas sin encabezado solo existen en extensiones personalizadas

Si un renderizador ignora tu tabla, comprueba primero el número de columnas: una fila separadora que no coincide con la fila de encabezado impide por completo el reconocimiento de la tabla. La otra causa común es la falta de una línea en blanco antes de la tabla — el número de guiones casi nunca es el problema.

Alineación de columnas — izquierda, centro, derecha

Añade dos puntos : a la fila separadora para controlar la alineación:

| Product | Qty | Price |
| :--- | :---: | ---: |
| Apples | 3 | 1.20 |
| Oranges | 10 | 0.80 |

Alinear a la derecha las columnas numéricas mantiene los dígitos alineados y hace que la tabla sea más fácil de leer.

Compatibilidad con GFM (GitHub Flavored Markdown)

GitHub, GitLab, Zenn, Qiita, Notion, Obsidian y la mayoría de las plataformas orientadas a desarrolladores admiten la sintaxis de tablas GFM. Todo lo mostrado arriba funciona tal cual en estas plataformas.

Algunas cosas que conviene recordar sobre las tablas GFM:

• La fila de encabezado es obligatoria. No puedes crear una tabla sin encabezado en GFM
• La fila separadora usa guiones (---): tres por columna por convención, aunque la especificación permite menos
• El formato en línea (`code`, enlaces, tachado) funciona dentro de las celdas
• Algunos analizadores exigen una línea en blanco antes y después de la tabla para reconocerla

Compatibilidad de tablas con barras por plataforma

Los tres elementos básicos de una tabla — las tablas con barras |, la alineación con dos puntos en la fila separadora (:---) y <br> para un salto de línea dentro de la celda — tienen un soporte desigual entre plataformas. La siguiente tabla resume el comportamiento de cada plataforma, con las notas por plataforma debajo:

Notas sobre la tabla:

• GitHub sigue la especificación de GitHub Flavored Markdown — Tablas (extensión)Se abre en una pestaña nueva, que define las tablas con barras y la alineación con dos puntos en la fila delimitadora. Las celdas se analizan como contenido en línea, por lo que se admite HTML en bruto en línea como <br>, y GitHub lo renderiza como un salto de línea dentro de la celda.
• GitLab Flavored Markdown documenta la misma sintaxis de tablas con barras y alineación, y su documentación señala explícitamente que puedes usar una etiqueta <br> para forzar varias líneas dentro de una celda.
• Obsidian admite las tablas con barras y la alineación con dos puntos en su sintaxis de tablas documentada y, en la práctica, renderiza una etiqueta <br> como un salto de línea dentro de la celda.
• Notion puede importar o pegar tablas con barras, pero las convierte en sus propios bloques de tabla en lugar de renderizar GFM. Las tablas de Notion no tienen alineación por columna, así que los dos puntos de alineación (:---) no tienen ningún efecto visible, y un <br> dentro de la celda no se renderiza como salto de línea.

Las reglas exactas están en la especificación de GitHub Flavored Markdown — Tablas (extensión)Se abre en una pestaña nueva. El CommonMarkSe abre en una pestaña nueva puro no define la sintaxis de tablas, por lo que las tablas son técnicamente una extensión de GFM. Los renderizadores que siguen CommonMark estricto (sin extensiones) no las mostrarán como tablas. Para conocer el conjunto completo de diferencias entre CommonMark y GFM, consulta CommonMark vs GFM; para una referencia rápida de la sintaxis de tablas GFM — alineación, escapado, saltos de línea — consulta la chuleta de tablas GFM.

Comportamiento real de la fila separadora — 4 renderizadores medidos (GitHub / marked / remark-gfm / CommonMark)

La extensión de tablas de GFM define la fila separadora solo como celdas "whose only content are hyphens (-), and optionally, a leading or trailing colon (:)" (cuyo único contenido son guiones y, opcionalmente, dos puntos al principio o al final). En ninguna parte de la especificación aparece un número mínimo de guiones. La documentación del propio GitHub dice que cada columna necesita al menos tres, pero la especificación no fija esa regla y el renderizador de GitHub acepta uno solo: el propio ejemplo de alineación de la especificación usa :-: con un único guion.

Para fijar esta afirmación pasamos el mismo conjunto de casos límite por el renderizador de producción de GitHub (vía su Markdown API), marked, remark-gfm y una cadena CommonMark estricta sin extensiones. El script de reproducción está en scripts/benchmarks/markdown-table-parsers/ dentro del repositorio. Medido el 2026-07-15 con marked 18.0.5, remark-gfm 4.0.1 y remark-parse 11.0.0:

Tres hallazgos que conviene retener:

• El número de guiones nunca decide si la tabla se renderiza. Un guion se comporta exactamente igual que tres en GitHub, marked y remark-gfm — los tres guiones son una convención de legibilidad, no un requisito
• La única diferencia real entre analizadores está en la penúltima fila: si omites las barras exteriores y usas un solo guion, la línea separadora empieza por - , que GitHub y remark-gfm leen como marcador de lista; marked sigue viendo una tabla. Si omites las barras exteriores, deja al menos dos guiones
• Lo que rompe la tabla de forma fiable en todas partes es una fila separadora cuyo número de columnas no coincide con el encabezado. La tabla simplemente no se reconoce y cae a párrafo, sin ningún mensaje de error

El script de reproducción y los datos crudos están en el repositorio del sitio, en scripts/benchmarks/markdown-table-parsers/.

Cómo escapar barras y caracteres especiales

Una | literal dentro de una celda choca con el separador de columnas y rompe la tabla. Hay dos maneras de escribirla de forma segura:

| Command | Meaning |
| --- | --- |
| cmd1 \| cmd2 | backslash escape |
| cmd1 | cmd2 | HTML entity |

• \| (escape con barra invertida) funciona en GitHub, GitLab, Notion, Obsidian, Zenn, Qiita y la mayoría de los renderizadores GFM
• | (entidad numérica HTML) es una alternativa fiable cuando un renderizador no maneja bien la forma con barra invertida, y resiste mejor el copiar y pegar entre editores que \|

Para mostrar una barra invertida literal en una celda, escribe \\. Para insertar un espacio de no separación, usa  .

Fuera de las tablas se aplica la misma regla de la barra invertida cuando caracteres como * y # se convierten en formato por su cuenta. Los caracteres de escape de Markdown enumeran todos los símbolos escapables y cuáles surten efecto en cada renderizador.

Envolver la barra en backticks tampoco la protege, aunque algunas guías describen los backticks como intrínsecamente seguros frente a la sintaxis de tablas. La división de celdas ocurre antes de que se interpreten los elementos en línea, así que una barra dentro de backticks sigue necesitando el escape con barra invertida:

| a | b |
| --- | --- |
| `x | y` | z |

Al pasar esta fila por la API de Markdown de GitHub, marked 18.0.5 y remark-gfm 4.0.1, los tres renderizadores dividen la celda del código: la salida tiene solo dos celdas <td>, `x y y`, con los backticks sin emparejar mostrados como caracteres literales, y el tercer valor z se pierde en silencio (medido el 2026-08-29, pasos de reproducción en scripts/benchmarks/markdown-table-parsers/). El escape con barra invertida sigue funcionando dentro de un backtick — el caso `a \| b` del mismo benchmark se mantiene intacto en los tres renderizadores, así que \| sigue siendo la solución aquí. Tablas Markdown que no se renderizan — soluciónalo por síntoma repasa este patrón junto con otras causas de división de celdas.

Errores comunes

Si una tabla se muestra como barras literales o se corta a mitad, la causa suele ser uno de los patrones siguientes. Para un diagnóstico basado en síntomas, consulta Tablas Markdown que no se renderizan — soluciónalo por síntoma.

Saltos de línea dentro de las celdas

La especificación de tablas Markdown no admite saltos de línea dentro de una celda. Si necesitas un salto visible, escribe directamente una etiqueta HTML <br>, aunque no todas las plataformas la renderizan.

Celdas vacías

Deja un espacio (o nada) entre dos barras. Se prefiere un espacio para mayor legibilidad:

| A | B | C |
| --- | --- | --- |
| 1 | | 3 |

Número de columnas que no coincide

Si una fila de datos tiene menos columnas que el encabezado, la mayoría de los analizadores las rellenan con celdas vacías. Si tiene más, las sobrantes se descartan en silencio. Mantener un número de columnas coherente evita sorpresas.

Conjuntos de datos grandes — genéralos desde CSV

Escribir a mano una tabla de cinco filas no cuesta nada. Pero pasando de 20 filas, o con muchas columnas, se vuelve tedioso y propenso a errores. Copia los datos de Excel o de una hoja de cálculo como CSV, pégalos en CSV a Markdown y la herramienta se encarga por ti de la alineación de las barras y del escapado.

Para un recorrido paso a paso, consulta Cómo convertir CSV en una tabla Markdown. Si necesitas convertir la tabla Markdown resultante en HTML, consulta la guía de conversión de Markdown a HTML. Para extraer una tabla Markdown de un HTML existente — una página web copiada, una exportación de Notion o un volcado de un CMS — consulta la guía de HTML a Markdown. Si solo te interesan las tablas, incluidas las celdas con barras verticales y saltos de línea, consulta cómo convertir una tabla HTML a Markdown.

Preguntas frecuentes

¿Puedo crear una tabla Markdown sin encabezado?

En GFM no. Tanto la fila de encabezado como la fila separadora son obligatorias. Si no necesitas encabezados visibles, igual tienes que incluirlos: usa texto de marcador de posición o celdas de encabezado vacías.

¿Puedo poner enlaces o imágenes dentro de una celda?

Sí. El Markdown en línea como [text](url) y ![alt](image-url) funciona dentro de las celdas. Ten en cuenta que las celdas anchas hacen que el código fuente sea difícil de leer, por lo que los enlaces suelen ser el límite práctico.

¿Puedo controlar el ancho de las columnas?

Markdown no tiene sintaxis para el ancho de columnas. Los renderizadores ajustan el tamaño de las columnas según el contenido. Para un control preciso, recurre a una <table> de HTML.

Conclusión

La sintaxis de las tablas Markdown es sencilla: barras para las columnas, guiones para el separador y dos puntos para la alineación. Una vez que conoces estas tres piezas, puedes construir cualquier tabla.

Cuando los datos crecen, ahórrate el trabajo manual. Pega tu CSV en CSV a Markdown y obtén una tabla limpia y correctamente escapada en segundos.

Artículos relacionados

• Chuleta de tablas GFM — referencia rápida para alineación, escapado y saltos de línea
• Tablas de README de GitHub a partir de CSV y JSON — caso de uso práctico de README
• CommonMark vs GFM — contexto más amplio de la especificación, incluidas las tablas
• Tablas Markdown que no se renderizan — soluciónalo por síntoma — diagnóstico basado en síntomas cuando una tabla falla
• Convertir tabla HTML a Markdown — convierte una tabla HTML copiada o exportada en una tabla de barras