Hoja de referencia de tablas Markdown en GitHub: alineación, celdas vacías y saltos de línea

TL;DR — Hoja de referencia de tablas GFM

Una tabla GFM es una tabla separada por pipes definida por la especificación de GitHub Flavored Markdown, una extensión de CommonMark que el CommonMark estricto no incluye.

• Una tabla consta de una fila de encabezado, una fila separadora (---, al menos tres guiones por columna) y filas de datos, todas divididas por pipes |. Se requiere una línea en blanco antes y después de la tabla.
• La alineación se define con dos puntos en la fila separadora: :--- a la izquierda, :---: al centro, ---: a la derecha.
• Un pipe literal dentro de una celda se escribe \| (escape con barra invertida); | (entidad HTML) es la alternativa cuando un renderizador no maneja bien la forma con barra invertida.
• Un salto de línea visible dentro de una celda es una etiqueta <br> literal. Funciona en GitHub y GitLab; en Obsidian, Notion y otros varía según el modo de edición o la vía de importación.
• La combinación de celdas, los párrafos múltiples, los bloques de código y otros elementos de bloque no son posibles en las tablas GFM. Usa una <table> de HTML cuando los necesites.
• ¿No quieres escribir los pipes a mano? Pega CSV en CSV a Markdown y obtén una tabla compatible con GFM al instante.

Esta es una tarjeta de consulta rápida para quienes ya saben más o menos cómo escribir una tabla Markdown. Si quieres aprender a construir una desde cero, empieza por Tablas en Markdown: sintaxis, alineación y ejemplos para copiar.

Qué pueden y qué no pueden hacer las tablas GFM

Cuando necesites elementos de bloque o celdas combinadas, escribe una <table> de HTML directamente en tu Markdown (consulta "Qué no pueden hacer las tablas Markdown" más abajo).

Estructura básica — el par mínimo

Una tabla GFM tiene tres partes: una fila de encabezado, una fila separadora y filas de datos. El separador necesita al menos tres guiones por columna; los pipes inicial y final son opcionales.

Sintaxis:

| Name | Role |
| --- | --- |
| Mika | admin |
| Noah | viewer |

Renderizado:

La tabla más pequeña posible (una fila de encabezado + una fila de datos):

| key | value |
| --- | --- |
| name | FormatArc |

Hoja de referencia de la sintaxis de alineación

La posición de los dos puntos en la fila separadora define la alineación de la columna.

Sintaxis:

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

Renderizado:

Alinear a la derecha las columnas numéricas mantiene los dígitos en línea y facilita la lectura.

Formato en línea dentro de las celdas

Las celdas aceptan elementos en línea. No se permiten bloques de código, listas ni párrafos múltiples.

Las imágenes funcionan en las celdas, pero hacen la tabla alta y difícil de leer, así que los iconos pequeños son el límite práctico.

Celdas vacías y en blanco

Dejar una celda vacía está permitido: no pongas nada entre los pipes y la celda se renderiza en blanco.

Sintaxis:

| Name | Role | Note |
| --- | --- | --- |
| Mika | admin | |
| Noah | | viewer |

Renderizado:

Hay dos cosas que suelen confundir:

• El número de columnas tiene que seguir coincidiendo. Una celda vacía es | |, dos pipes sin nada en medio, no un pipe omitido. Si quitas un pipe, la fila tiene una columna menos y la tabla se desalinea.
• Cuando la primera celda de una fila está vacía y además omites el pipe inicial, algunos renderizadores pierden la primera columna de la fila. Mantén el | inicial (| | value |) o, como alternativa, pon un enlace vacío []() en esa primera celda para que no se considere ausente.

Una celda vacía no es una celda combinada. GFM no tiene rowspan ni colspan, así que una celda en blanco simplemente está en blanco: no se une visualmente con la celda de arriba ni con la de al lado. Cuando necesites combinar, cambia a una <table> de HTML (consulta más abajo).

Escapar pipes y caracteres especiales

Un | literal dentro de una celda choca con el separador de columnas y rompe la tabla. Hay dos formas seguras de escribirlo:

Sintaxis:

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

Renderizado:

Para mostrar una barra invertida literal, escribe \\; para un espacio de no separación, usa  . Si construyes tablas a partir de CSV o HTML, el escape de pipes lo gestionan por ti CSV a Markdown y HTML a Markdown, así que no tienes que pensar en ello.

Saltos de línea dentro de las celdas, por plataforma

La especificación de tablas Markdown no admite saltos de línea literales dentro de una celda. Para un salto visible, escribe una etiqueta <br> literal, pero la compatibilidad varía.

Si una tabla necesita saltos de línea fiables en muchas columnas, no la fuerces a ser una tabla GFM: usa una <table> de HTML o divide las columnas.

Por qué se rompen las tablas — una lista de verificación

Cuando una tabla se renderiza mal, comprueba lo siguiente de arriba abajo:

• ¿Hay una línea en blanco antes y después de la tabla? Una tabla pegada a la línea anterior puede no reconocerse (sobre todo en GitHub).
• ¿Hay una fila de encabezado? GFM la exige. Si no quieres encabezados visibles, aun así necesitas una fila de encabezado vacía más el separador.
• ¿La fila separadora tiene al menos tres guiones por columna? -- no se renderiza como tabla en algunos renderizadores.
• ¿Las filas de encabezado, separadora y de datos tienen el mismo número de columnas (pipes)? Las filas de datos cortas se rellenan con celdas vacías; las largas pierden las celdas sobrantes.
• ¿Hay un | sin escapar dentro de una celda? Si es así, cámbialo por \| o |.
• ¿Hay una fila con sangría (cuatro o más espacios al inicio)? Puede confundirse con un bloque de código.
• ¿Hay un elemento de bloque (bloque de código, lista) dentro de una celda? No está permitido en las tablas GFM.

Generar tablas a partir de CSV / HTML / JSON

Escribir a mano una tabla de cinco filas está bien. Pasadas las 20 filas, o con muchas columnas, la alineación de pipes y el escape se vuelven propensos a errores. Según el formato de origen, una herramienta de FormatArc lo convierte en una tabla compatible con GFM en un solo paso.

• Desde CSV / una hoja de cálculo / Excel: pega en CSV a Markdown y ejecuta. Para un recorrido paso a paso, consulta Cómo convertir CSV en una tabla Markdown; para su uso en README, consulta Agregar una tabla a un README de GitHub.
• Desde HTML existente (una tabla de una página web, una exportación de Notion, un volcado de un CMS): pega el HTML en HTML a Markdown y los elementos <table> se convierten en tablas de pipes. Consulta la guía de HTML a Markdown.
• Desde JSON (una respuesta de API o registros): pásalo por CSV. Construye un CSV donde las claves de cada objeto sean los nombres de las columnas y los valores sean las celdas de las filas, y luego pásalo a CSV a Markdown. Consulta la sección "Construir una tabla a partir de datos JSON" en Agregar una tabla a un README de GitHub.
• Para pegar la tabla Markdown resultante en un CMS que no admite Markdown, o en un correo HTML, conviértela con Markdown a HTML. Consulta la guía de Markdown a HTML.

Todo se ejecuta en tu navegador, así que los datos internos y las listas de clientes nunca se envían a un servidor. Sin registro, sin subida de archivos.

Si la tabla va destinada a un prompt para un LLM, una tabla Markdown cuesta muchos menos tokens que el HTML equivalente y se extrae con mayor precisión. Consulta Markdown frente a HTML para LLM para ver la comparación medida de tokens y precisión.

Qué no pueden hacer las tablas Markdown — cuándo cambiar a HTML

Las tablas GFM no pueden expresar lo siguiente. En su lugar, cambia a una <table> de HTML literal dentro de tu Markdown:

• Celdas combinadas entre filas o columnas (rowspan / colspan)
• Listas con viñetas, párrafos múltiples o bloques de código dentro de una celda
• Anchos de columna fijos en píxeles o porcentajes
• Un encabezado u otra tabla anidada dentro de una tabla

Ten en cuenta que GitHub y plataformas similares restringen el HTML dentro de las tablas por seguridad: <br> pasa, pero los estilos en línea como <span style="..."> se ignoran, así que no puedes cambiar colores ni tamaños de fuente de esa manera.

CommonMark y las tablas

CommonMark puro no define una sintaxis de tablas. Las tablas de pipes son una extensión de GFM, definida en la sección de tablas (extensión) de la especificación de GitHub Flavored Markdown. Un renderizador que implementa CommonMark estricto sin extensiones mostrará | col | como texto plano, no como una tabla. La forma más rápida de saber si tu herramienta es compatible con GFM es escribir una tabla simple y ver si se renderiza.

Preguntas frecuentes

¿Cuál es la tabla Markdown más pequeña?

Tres líneas: una fila de encabezado, una fila separadora y una fila de datos. Escribe | key | value |, luego | --- | --- | debajo, y después | name | FormatArc |. La fila separadora necesita al menos tres guiones por columna.

¿Cómo dejo una celda vacía?

No pongas nada entre los dos pipes: | value | |. El número de columnas tiene que seguir coincidiendo con el encabezado, así que una celda vacía es | |, no un pipe omitido. Si la celda vacía es la primera de una fila, mantén el pipe inicial (| | value |); algunos renderizadores eliminan la primera columna de una fila cuando faltan tanto el pipe inicial como la celda. Una celda en blanco no es una celda combinada; GFM no tiene rowspan ni colspan.

¿Debería usar \| o |?

Usa primero el escape con barra invertida \|. Está documentado por GitHub y funciona en la mayoría de los renderizadores GFM. Recurre a | solo cuando un renderizador no maneje bien \| o cuando copiar y pegar entre editores lo rompa.

¿Puedo cambiar el color del texto o el tamaño de fuente dentro de una celda?

No solo con tablas GFM. GitHub y plataformas similares ignoran los estilos en línea como <span style="..."> dentro de las tablas, así que los cambios de color y tamaño no se aplican. Si necesitas dar estilo a las celdas, saca la tabla y usa HTML, o replantea el diseño.

¿Hay alguna recomendación para los anchos de columna?

Markdown no tiene sintaxis de ancho de columna; los renderizadores ajustan las columnas al contenido. Como regla práctica, si un README o documento se lee tanto en escritorio como en móvil, mantén las tablas en cinco o seis columnas. Más allá de eso, GitHub añade desplazamiento horizontal y la tabla se vuelve difícil de leer.

¿Puedo combinar celdas (rowspan / colspan)?

No en las tablas GFM. Para celdas combinadas, escribe una <table> de HTML directamente en tu Markdown, pero revisa primero el resultado renderizado, ya que GitHub y otros restringen algunos atributos HTML.

Mi tabla aparece como | col | en lugar de renderizarse. ¿Por qué?

Las causas habituales: no hay una línea en blanco antes o después de la tabla, hay menos de tres guiones en la fila separadora, falta la fila de encabezado, el número de columnas no coincide, o el renderizador no admite la extensión de tablas de GFM (CommonMark estricto). Repasa la lista de verificación "Por qué se rompen las tablas" de arriba abajo.

Artículos relacionados

• Tablas en Markdown: sintaxis, alineación y ejemplos para copiar — un tutorial paso a paso para construir una tabla desde cero
• Cómo convertir CSV en una tabla Markdown — conversión en un paso desde datos de Excel o de una hoja de cálculo
• Agregar una tabla a un README de GitHub — genera tablas para README a partir de CSV / JSON
• Guía de conversión de Markdown a HTML — pega tu tabla en un CMS que no admite Markdown
• Guía de HTML a Markdown — extrae tablas de páginas web o exportaciones de Notion