Si necesitas una tabla en tu README, la vía más rápida es pegar tu CSV en CSV a Markdown y pulsar Ejecutar. Genera una tabla compatible con GFM que puedes copiar directamente en tu README, todo dentro del navegador.
Este artículo explica cuándo conviene usar tablas en el README, cómo generarlas a partir de CSV o JSON y qué tener en cuenta con GitHub Flavored Markdown.
Cuándo un README necesita una tabla
El texto plano funciona hasta que la información crece. Los siguientes tipos de contenido se leen mucho mejor en forma de tabla:
- Listas de endpoints de API (ruta, método, descripción)
- Versiones compatibles o matrices de compatibilidad de plataformas
- Comparativas de funciones (tu proyecto frente a alternativas, o gratuito frente a de pago)
- Referencias de opciones de la CLI
- Listas de variables de entorno con sus valores por defecto
Las listas con viñetas se extienden verticalmente y dificultan la comparación entre columnas. Una tabla permite que el lector recorra la información horizontalmente y detecte las diferencias de inmediato.
Ejemplos reales de tablas en README
Las cinco categorías anteriores son abstractas. Así es como se ven en la práctica como tablas Markdown que puedes usar hoy mismo en un README.
Referencia de opciones de la CLI — toda herramienta de línea de comandos acaba teniendo una lista de flags. Una tabla vence a un muro de texto de --help:
| Flag | Default | Description |
| :--- | :--- | :--- |
| `--port` | `3000` | HTTP port to listen on |
| `--host` | `0.0.0.0` | Bind address |
| `--log-level` | `info` | One of `debug`, `info`, `warn`, `error` |
Matriz de compatibilidad de versiones — el soporte de runtime es el motivo más habitual para consultar un README:
| Runtime | Minimum | Tested up to | Status |
| :--- | ---: | ---: | :--- |
| Node.js | 18.x | 22.x | LTS supported |
| Bun | 1.0 | 1.1 | Best effort |
| Deno | 1.40 | 2.0 | Community |
Comparativa de funciones frente a alternativas — presente en cualquier sección de "por qué esta librería":
| Feature | This project | Alternative A | Alternative B |
| :--- | :---: | :---: | :---: |
| Zero dependencies | ✅ | ❌ | ✅ |
| TypeScript types | ✅ | ✅ | ❌ |
| Browser-side | ✅ | ❌ | ❌ |
Cada una de estas es pequeña (3-4 filas, 3-4 columnas) a propósito: GitHub las renderiza sin desplazamiento horizontal en móvil y siguen siendo legibles cuando el README crece.
Conceptos básicos de las tablas Markdown
Las tablas de GFM usan el carácter de barra vertical como separador de columnas:
| Command | Description |
| --- | --- |
| install | Install dependencies |
| build | Build for production |
| test | Run the test suite |
La primera fila es el encabezado, la segunda es el separador y todas las filas siguientes son datos. Agrega : al separador para controlar la alineación (:--- izquierda, :---: centro, ---: derecha).
Para profundizar en la sintaxis, consulta Sintaxis de tablas en Markdown.
Generar una tabla para el README a partir de CSV
Cuando tus datos viven en una hoja de cálculo o en un archivo CSV, usa CSV a Markdown:
- Abre CSV a Markdown
- Pega tu CSV en el editor de la izquierda (también funciona copiar y pegar desde Excel o Google Sheets)
- Pulsa Ejecutar
- Copia la tabla Markdown del panel derecho en tu README
Todo se ejecuta en el navegador: ningún dato sale de tu equipo. Para más detalles sobre casos límite y escapado, consulta Cómo convertir CSV en una tabla Markdown.
¿No tienes claro si los datos deberían estar en JSON, YAML, CSV o Markdown? La hoja de comparación de formatos de datos resume cuándo usar cada formato.
Crear una tabla a partir de datos JSON
A veces tus datos empiezan como JSON: la respuesta de una API, un volcado de configuración, un extracto de registros. La ruta más fiable hacia una tabla Markdown es pasar primero por CSV.
Para un recorrido más detallado que cubre arrays, objetos anidados y respuestas de API, consulta Cómo convertir JSON en una tabla Markdown.
Pasos
- Da formato al JSON con el Formateador de JSON para verificar su estructura
- Convierte el array JSON a CSV (las claves de los objetos pasan a ser los encabezados de columna y los valores, las celdas de cada fila)
- Pega el CSV en CSV a Markdown para generar la tabla
Por ejemplo, dado este JSON:
[
{ "name": "Node.js", "version": "20.x", "status": "LTS" },
{ "name": "Node.js", "version": "22.x", "status": "Current" }
]
El equivalente en CSV es:
name,version,status
Node.js,20.x,LTS
Node.js,22.x,Current
Pega eso en CSV a Markdown y la tabla queda lista para tu README.
Errores comunes en las tablas de README
La mayoría de las tablas de README "rotas" se reducen a cuatro errores. Saber cuál de ellos es el culpable te ahorra una larga búsqueda por el código fuente en Markdown. Conviene aclarar algo antes de la lista: la especificación GFM, sección 4.10Se abre en una pestaña nueva describe la fila delimitadora como celdas "cuyo único contenido son guiones (-) y, opcionalmente, dos puntos (:) al principio o al final". No fija un número mínimo de guiones ni exige una línea en blanco antes de la tabla.
Número de columnas inconsistente
La fila delimitadora fija el número de columnas. Cualquier fila con más celdas pierde las sobrantes en silencio; cualquier fila con menos celdas recibe celdas vacías añadidas al final.
| name | role |
| --- | --- |
| Alice | Engineer | LA ← celda sobrante, descartada en silencio
| Bob ← falta una celda, se renderiza vacía
GitHub no avisa de esto. Si la columna derecha de tu tabla está misteriosamente vacía, cuenta los pipes de la fila problemática.
Fila delimitadora ausente o mal formada
La fila delimitadora es lo que convierte el bloque en una tabla, así que equivocarse ahí produce el fallo de "no hay tabla en absoluto". Lo que importa es el número de columnas, no la cantidad de guiones.
| name | role |
| --- | ← una celda delimitadora para dos columnas de encabezado: no hay tabla en ningún parser
| Alice | Engineer |
Pasé ese caso por cuatro parsers (scripts/benchmarks/markdown-table-parsers/ en el repositorio, medido el 2026-07-15 con la API de Markdown de GitHub, marked 18.0.5, remark-gfm 4.0.1 y CommonMark estricto vía remark-parse). Un desajuste en el número de columnas no produjo tabla en ninguno de los cuatro.
La cantidad de guiones es otra historia. En la misma medición, tanto | - | - | como | -- | -- | se renderizaron como tablas en la API de GitHub, marked y remark-gfm. Tres guiones es una convención de legibilidad, no un requisito: la propia documentación de GitHub dice tres o más, la especificación no dice nada y las implementaciones aceptan uno. Por eso, cuando una tabla no se renderiza, contar guiones es el punto de partida equivocado. El mismo mito se trata en detalle en Por qué se rompe tu tabla de Markdown.
Hay un caso en el que una fila delimitadora corta sí molesta: si omites los pipes exteriores y usas un solo guion, GitHub interpreta el bloque como una lista.
h1 | h2
- | - ← aquí GitHub renderiza una lista; `--- | ---` sí renderiza una tabla
a | b
Si una tabla se niega a renderizarse en GitHub pero funciona en tu editor, revisa primero el número de columnas de la fila delimitadora y después si están los pipes exteriores.
Celdas vacías en GitHub vs editores
GFM permite celdas realmente vacías:
| feature | basic | pro |
| :--- | :---: | :---: |
| Export PDF | | ✅ |
| API access | | ✅ |
GitHub renderiza las celdas vacías correctamente. Algunos editores colapsan la fila visualmente porque interpretan los pipes consecutivos como un error de sintaxis. El código Markdown está bien: la vista previa del editor es la que está mal. Renderiza en GitHub para confirmarlo.
El carácter pipe | literal dentro de una celda
Un carácter pipe dentro de una celda termina la columna. Escápalo con una barra invertida, o usa la entidad HTML |:
| condition | meaning |
| --- | --- |
| `a \| b` | bitwise or |
| `a | b` | same, via entity |
Ambos se renderizan como a | b en GitHub. La barra invertida es la forma estándar de GFM; la entidad HTML es una alternativa más segura si tu README se procesa con un toolchain que no es GFM (Hugo, MkDocs).
Si tu tabla se renderiza correctamente al pegarla en GitHub pero se ve rota en tu editor local, normalmente el problema es el editor: la vista previa en github.com es la fuente de verdad para cualquier tabla de README.
Particularidades de las tablas GFM en GitHub
El renderizador de Markdown de GitHub se comporta de forma distinta a los editores de Markdown de propósito general en varios aspectos.
Saltos de línea en celdas con <br>
La especificación de tablas GFM no permite saltos de línea literales dentro de las celdas. Una celda de varias líneas escrita así se aplana a una sola línea:
| step | description |
| --- | --- |
| 1 | install dependencies
then build |
Usa <br> en su lugar — GitHub lo renderiza como un salto de línea dentro de la celda:
| step | description |
| --- | --- |
| 1 | install dependencies<br>then build |
| 2 | run tests<br>commit the lockfile |
<br> es una de las pocas etiquetas HTML que sobreviven al saneador de Markdown de GitHub dentro de las tablas (consulta la siguiente sección). La mayoría de los editores lo muestran correctamente en la vista previa, pero si el tuyo no lo hace, pega el README en un GitHub Gist para verificar cómo se renderiza realmente.
Formato dentro de las celdas: énfasis, código, enlaces, insignias
El Markdown en línea funciona dentro de las celdas, y eso es lo que hace útiles las tablas de README como paneles de estado y cuadros comparativos. El énfasis, el código en línea, los enlaces, las imágenes y los emoji se renderizan todos:
| Package | Status | Docs |
| --- | --- | --- |
| `core` |  | [Read](./docs/core.md) |
| `cli` | :warning: experimental | [Read](./docs/cli.md) |
Dos cosas no funcionan. Los elementos de bloque (encabezados, listas, bloques de código con vallas) no se pueden anidar en una celda: un # al principio de una celda se queda como un # literal. Y cualquier | dentro de una URL de shields.io o de un enlace de imagen parte la celda, así que las cadenas de consulta como ?label=a|b necesitan el pipe escapado como \| o codificado como %7C. Es la misma regla de escape de la sección "El carácter pipe | literal dentro de una celda" de más arriba, pero es fácil pasarla por alto cuando el pipe está enterrado en una URL en lugar de en el texto.
Si generas la tabla a partir de CSV o JSON, deja el Markdown de la insignia en la celda de origen: CSV to Markdown lo pasa sin modificar, así que la columna de insignias sobrevive a cada regeneración.
HTML limitado dentro de las tablas
GitHub elimina la mayor parte del HTML en línea por seguridad. <br> funciona para los saltos de línea dentro de una celda, pero <span style="..."> y otros estilos en línea similares se ignoran. No dependas de cambios de color o de tamaño de fuente dentro de las celdas de una tabla.
Alineación de columnas
La sintaxis de alineación con : en la fila separadora funciona como se espera en GitHub. Alinear a la derecha las columnas numéricas facilita la lectura de números de versión y precios.
| Plan | Monthly |
| :--- | ---: |
| Free | $0 |
| Pro | $10 |
Tablas anchas y desplazamiento horizontal
Las tablas con muchas columnas provocan desplazamiento horizontal en GitHub. Si los lectores van a ver el README tanto en escritorio como en móvil, limita las tablas a cinco o seis columnas, o divídelas en tablas separadas.
Preguntas frecuentes
¿Puedo gestionar las tablas del README en una hoja de cálculo?
Sí. Mantén los datos de origen en una hoja de cálculo, exporta el CSV cada vez que cambie el contenido y pásalo por CSV a Markdown para regenerar la tabla. Pega el resultado en el README y haz commit.
¿Puedo poner enlaces dentro de las celdas de una tabla?
Sí. La sintaxis estándar de enlaces de Markdown [texto](url) funciona dentro de las celdas de las tablas GFM y se muestra como un enlace en el que se puede hacer clic en GitHub.
¿Cómo agrego saltos de línea dentro de una celda?
Usa la etiqueta HTML <br> dentro de la celda. Consulta la sección "Saltos de línea en celdas con <br>" más arriba para ver ejemplos y limitaciones.
Para terminar
Las tablas hacen que el contenido del README sea fácil de recorrer con la vista. Escribir las barras verticales a mano está bien para unas pocas filas, pero cualquier cosa más grande pide automatización. CSV a Markdown genera la tabla a partir del CSV pegado en segundos, así puedes dedicar tu tiempo al contenido en lugar de al formato.