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.
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.
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.
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.
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?
La especificación de tablas de GFM no admite saltos de línea literales dentro de las celdas. Usa una etiqueta <br>: GitHub la representa como un salto de línea dentro de la celda.
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.