Sintaxis de tablas Markdown en GitHub: 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 — al menos tres guiones - 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:

• Mínimo 3 guiones por columna en la fila separadora. Dos o menos (--) fallan en silencio: la mayoría de los renderizadores GFM dejan de tratarlo como una tabla
• 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
• 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, casi siempre el culpable es la fila separadora: pocos guiones, un número de columnas que no coincide o la falta de una línea en blanco antes de la tabla.

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 necesita al menos tres guiones (---) por columna
• 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), 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). El CommonMark 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.

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  .

Errores comunes

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.

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