La guía completa de las tablas de Markdown (2026)

Qué es de verdad una tabla de Markdown

Una tabla de Markdown es texto. Tres cosas la hacen una tabla: una fila de encabezado, una fila separadora de guiones y una o más filas de datos. Las barras verticales separan las celdas. El motor de renderizado lee la estructura y emite una <table> HTML con thead y tbody.

| Columna A | Columna B | Columna C |
|-----------|-----------|-----------|
| Celda 1   | Celda 2   | Celda 3   |
| Celda 4   | Celda 5   | Celda 6   |

Las barras verticales del inicio y del final son técnicamente opcionales en muchos analizadores. Pero inclúyelas. Reddit, Discord y unos cuantos generadores de sitios estáticos las exigen. Úsalas en todas partes y evita el dolor de cabeza entre plataformas.

Alineación — el único lugar donde la sintaxis sutil importa

La fila separadora controla la alineación de las columnas. Tres patrones:

• :----. Alineado a la izquierda (por defecto si no hay dos puntos)
• ----:. Alineado a la derecha
• :----:. Centrado

Los números deben ir alineados a la derecha. Los encabezados que nombran cosas contables suelen ir centrados. El texto del cuerpo va alineado a la izquierda. Acierta con esto una vez y cada tabla del sitio se lee mejor:

| Artículo | Cantidad | Precio   |
|:---------|---------:|---------:|
| Café     |        2 |   $7.00  |
| Bollo    |        3 |   $12.00 |

Escapado — barras verticales, barras invertidas y saltos de línea

Tres caracteres causan problemas de verdad dentro de las celdas.

Barras verticales. Una barra vertical literal dentro de una celda se interpreta como un límite de columna. Dos formas de escaparla: la entidad HTML | o una barra invertida \|. La mayoría de los analizadores modernos aceptan ambas. La herramienta Tabla de Markdown de TextKit escapa de forma automática las barras que escribes o pegas.

Barras invertidas. Ya son especiales en Markdown para escapar. Para producir una barra invertida literal, duplícala: \\.

Saltos de línea. Las tablas de Markdown no pueden contener saltos de línea literales dentro de las celdas. Para forzar un salto de línea, usa <br>. El analizador lo deja pasar como HTML en crudo. Este es el único lugar donde la vía de escape al HTML en línea es inevitable.

El flujo de pegar desde una hoja de cálculo

La mayoría de las tablas no se escriben a mano. Se pegan desde Excel, Google Sheets, Numbers o una exportación CSV. Tanto Excel como Sheets ponen el rango copiado en el portapapeles como texto separado por tabuladores. La conversión a Markdown es mecánica: reemplaza los tabuladores por |, añade una fila separadora y, si quieres, envuelve con barras verticales al inicio y al final.

El atajo: copia un rango desde Excel, haz clic en «Pegar desde hoja de cálculo» en la herramienta, haz clic en «Copiar Markdown». Cinco segundos.

Renderizado — en qué difiere cada plataforma

Markdown es una especificación, pero cada motor de renderizado interpreta los casos límite de forma distinta. Las diferencias que importan en la práctica:

Los valores por defecto seguros en todas partes: barras verticales al inicio y al final, alineación explícita con dos puntos, sin HTML dentro de las celdas y una fila separadora que coincida exactamente con el número de columnas del encabezado. Una tabla construida así se renderiza en cualquier entorno de Markdown que te encuentres en 2026.

Los cinco errores que causan el 90% de las tablas rotas

1. Número de columnas que no coincide. Tres columnas en el encabezado, cuatro celdas en la fila dos. La mayoría de los motores descartan o duplican celdas en silencio. Haz siempre un conteo rápido antes de publicar.
2. Falta la fila separadora. Sin la fila de guiones, el motor trata el bloque entero como párrafos. Fácil de olvidar al escribir a mano una tabla pequeña.
3. Espacios dentro de los guiones. La fila separadora es |---|---|, no |- - -|- - -|. Esto último es un párrafo con guiones literales.
4. Tabuladores de un pegado a medias. Los tabuladores no son barras verticales. Si tu «tabla» contiene tabuladores en vez de barras, ningún analizador de Markdown la reconocerá. Haz siempre un buscar y reemplazar para convertirlos.
5. Barras verticales dentro de las URL. Algunas URL (raro, pero pasa) contienen un | literal. Codifícalas siempre como %7C antes de ponerlas dentro de una celda de tabla de Markdown.

Cuándo usar una tabla en vez de una lista

Una tabla funciona cuando cada fila tiene el mismo conjunto de atributos. Una lista funciona cuando los elementos tienen atributos parciales o variables. La prueba de disciplina: si más de una columna quedaría vacía para alguna fila, los datos probablemente no son tabulares.

Las tablas también se vuelven ilegibles más allá de ~6 columnas en un escritorio y ~3 en el móvil. Pasado ese punto, cambia a una lista de definiciones (<dl>) o convierte cada fila en su propia tarjeta o bloque de párrafo.

Las tablas en la documentación técnica en particular

Para la documentación de API, las referencias de configuración y los listados de banderas de línea de comandos, las tablas suelen ser la opción correcta. La convención que ha surgido en los principales marcos de documentación:

• Columna 1: identificador (nombre de parámetro, nombre de bandera, clave). Alineado a la izquierda, monoespaciado con comillas invertidas en línea.
• Columna 2: tipo (string, boolean, number). Alineado a la izquierda.
• Columna 3: obligatorio u opcional. Centrado, texto plano.
• Columna 4: valor por defecto. Alineado a la izquierda, monoespaciado.
• Columna 5: descripción. Alineado a la izquierda, prosa simple, a menudo la columna más ancha.

Este patrón es lo que espera todo lector de documentación. Apartarse de él ralentiza al lector.

Tablas de Markdown frente a tablas HTML — cuándo bajar de nivel

Las tablas de Markdown son más fáciles de leer en el origen, pero pierden frente a las tablas HTML en tres cosas: las combinaciones de filas y columnas, las reglas complejas de alineación por celda y los estilos. Si una tabla necesita algo de eso, pasa a HTML en crudo dentro del documento Markdown. El análisis a fondo de Tablas de Markdown frente a HTML cubre el equilibrio en detalle.

La chuleta

• Fila de encabezado + fila separadora + filas de datos.
• Barras verticales al inicio y al final en todas partes. No cuesta nada y arregla Reddit y Discord.
• Los dos puntos en la fila separadora controlan la alineación.
• Alinea los números a la derecha. El texto a la izquierda. Centra las etiquetas cortas.
• Escapa las barras verticales como | o \| dentro de las celdas.
• Usa <br> para los saltos de línea dentro de una celda.
• Haz que el número de columnas coincida exactamente entre el encabezado y las filas de datos.
• Pasadas las 6 columnas, o 3 en el móvil, usa otra disposición.
• Pega desde Excel/Sheets con la herramienta Tabla de Markdown. Gestiona el TSV, el escapado y la alineación en un solo pegado.

Para más sobre el flujo de trabajo, mira Cómo hacer una tabla de Markdown en 60 segundos. Para una referencia imprimible, mira la chuleta de tablas de Markdown. Para el equilibrio frente a las tablas HTML, mira Tablas de Markdown frente a HTML.