Quieres colocar una tabla comparativa en un README de GitHub. Necesitas compartir cifras de benchmarks en la descripción de un pull request. Estás migrando notas de una hoja de cálculo a Notion u Obsidian. En todos estos casos, la pieza que falta es la misma: convertir datos con forma de CSV en una tabla Markdown limpia.
Pegar una hoja de cálculo directamente en GitHub no genera una tabla Markdown, y escribir las barras verticales a mano deja de ser práctico en cuanto pasas de unas pocas filas. Esta guía cubre la estructura de las tablas Markdown, los detalles que suelen pillar a la gente y cómo hacer la conversión en el navegador sin ninguna configuración.
¿Quieres la tabla ahora mismo? Pega tu CSV en la herramienta CSV a Markdown y pulsa Run: obtendrás una tabla compatible con GitHub. Si prefieres entender antes la sintaxis y los casos límite, sigue leyendo.
Qué hace la conversión
Empecemos por el lado del CSV, que es lo que vas a pegar:
name,email,role
Mika,mika@example.com,admin
Noah,noah@example.com,viewer
Al pasarlo por el conversor obtienes esto:
| name | email | role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |
La línea de cabecera se convierte en la fila de encabezado, debajo se inserta una fila separadora, y cada línea restante se convierte en una fila de datos con barras verticales alrededor y entre los campos. Esa es toda la transformación: el resto de este artículo trata sobre los casos en los que la entrada no es tan ordenada.
Cómo es una tabla Markdown
Las tablas de GitHub Flavored Markdown (GFM) usan el carácter de barra vertical como separador de columnas:
| name | email | role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |
La primera fila es el encabezado, la segunda fila es el separador de alineación y todo lo que va debajo son datos. Añadir : al separador controla la alineación de esa columna.
| Left | Center | Right |
| :--- | :---: | ---: |
| a | b | c |
La sintaxis es sencilla, pero escribirla a mano deja de escalar rápidamente. Una tabla de 20 filas y 5 columnas obliga a mantener todas las barras verticales alineadas mientras escribes, que no es precisamente como nadie quiere pasar el rato.
Por qué la conversión manual se vuelve dolorosa
Unas pocas filas no suponen problema. En el trabajo real, la fricción aparece de inmediato:
- El número de filas crece: las tablas comparativas en un README suelen superar las 30 filas
- Las celdas que contienen el carácter de barra vertical
|necesitan escaparse - Las celdas que contienen saltos de línea no caben en una tabla Markdown
- Los CSV con un número de columnas inconsistente producen tablas rotas
Los CSV exportados desde Excel son especialmente divertidos: los separadores de miles en los números pueden chocar con los delimitadores de columna, y los finales de línea al estilo Windows a veces rompen los parsers ingenuos.
Comparando las opciones
Hay más de una forma de convertir CSV en una tabla Markdown. Cuál te conviene depende de tu entorno y de cuántos datos manejes.
| Método | Configuración | Envía datos fuera del dispositivo | Tablas grandes | Escapa las barras automáticamente |
|---|---|---|---|---|
| Herramienta en el navegador (FormatArc) | Ninguna | No | Bien | Sí |
| CLI (csvtomd / csv2md) | Requiere pip / npm | No | Bien | Depende de la herramienta |
| A mano | Ninguna | No | Doloroso | Manual |
| Script awk / sed | Requiere conocer shell | No | Aceptable | Hazlo tú mismo |
Un CLI encaja bien en un pipeline, pero necesita instalación y un runtime. Escribir a mano está bien para pocas filas, pero se vuelve inviable a medida que crecen. Una herramienta en el navegador no necesita configuración, nunca sube lo que pegas y escapa las barras verticales por ti.
Convertir con FormatArc
CSV a Markdown toma el CSV que pegas y produce una tabla compatible con GFM. No hay nada que instalar.
Paso 1: Abre la herramienta
Ve a CSV a Markdown.
Paso 2: Pega tu CSV
Pega el CSV en el panel izquierdo. Funciona igual si copias desde Excel, Google Sheets o un archivo de texto plano. La primera fila se trata como el encabezado.
Paso 3: Pulsa Run
Pulsa Run. El panel derecho se rellena con la tabla Markdown.
La salida está lista para pegarse directamente en un README, un issue o un documento Markdown. El número de columnas y el ancho de los separadores se normalizan automáticamente.
Todo se ejecuta en el navegador. Las listas de clientes o las hojas de cálculo internas nunca se suben a un servidor. Para CSV sensibles, eso es más seguro que un conversor online basado en subida de archivos (consulta ¿son seguros los conversores online?).
Casos límite que conviene conocer
Barras verticales dentro de las celdas
Si una celda contiene |, el conversor la escapa automáticamente como \| para que no choque con el separador de columnas.
| x | y |
| --- | --- |
| foo\|bar | baz |
Si aun así la tabla sale rota después de pegarla en otro sitio, consulta qué hacer cuando una tabla Markdown no se muestra.
Saltos de línea dentro de las celdas
La especificación de tablas Markdown no tiene forma de representar saltos de línea dentro de las celdas. FormatArc los reemplaza por espacios. Si necesitas un salto de línea visible dentro de una celda, usa una etiqueta <br> explícita en tus datos de origen.
Filas irregulares
Si una fila de datos es más ancha que el encabezado, las columnas sobrantes se descartan. Si una fila de datos es más corta, las celdas que faltan se rellenan con cadenas vacías. En cualquier caso, la salida sigue siendo una tabla válida.
Campos entre comillas
Un campo CSV envuelto entre comillas dobles puede contener el propio delimitador, así que "Tokyo, Japan" es una sola celda y no dos. Las comillas forman parte de la sintaxis CSV, no de los datos, y no aparecen en la salida Markdown:
name,location,note
Mika,"Tokyo, Japan","said ""ok"" twice"
| name | location | note |
| --- | --- | --- |
| Mika | Tokyo, Japan | said "ok" twice |
Una comilla doblada dentro de un campo entre comillas ("") es el escape CSV para una comilla literal ", por eso la columna note sale con comillas normales. Si tu tabla muestra comillas sueltas o un valor partido en dos columnas, normalmente el CSV de origen está mal citado, no que el conversor lo gestione mal.
A dónde va la tabla convertida
READMEs de GitHub
Listas de endpoints de API, opciones admitidas, comparativas de librerías: las tablas en los README aparecen constantemente. Mantener el origen como CSV permite regenerar la tabla cada vez que cambian los datos subyacentes.
Pull requests e issues
Las cifras de benchmarks, las matrices de pruebas de regresión y los resúmenes de decisiones de diseño se leen mejor como tablas. Reúne los datos en una hoja de cálculo, pásalos por el conversor y pega.
Notion, Obsidian, Zenn, Qiita
La mayoría de las herramientas de notas y de publicación para desarrolladores hablan Markdown. Almacenar los datos como CSV y convertirlos bajo demanda elimina la necesidad de reformatear las tablas cada vez que cambias de plataforma.
Contexto para LLM
Pasarle una tabla a ChatGPT, Claude o Gemini funciona mejor en Markdown que como HTML en bruto: usa menos tokens y se extrae con mayor precisión. Consulta Markdown vs HTML para LLMs para ver cifras medidas sobre el coste en tokens y la precisión de extracción de tablas.
Compatibilidad de renderizadores para la alineación
La sintaxis de alineación GFM (:---, :---:, ---:) tiene buen soporte en plataformas para desarrolladores, pero puede ignorarse silenciosamente o funcionar solo en parte en herramientas de publicación para el público general. Usa esta tabla cuando sospeches que una tabla se está renderizando con la alineación equivocada en algún punto de la cadena. Las filas marcadas como "documentado" siguen la especificación o documentación publicada por la propia plataforma; las filas marcadas como "reportado" reflejan un comportamiento ampliamente reportado por usuarios que no hemos vuelto a probar de forma independiente — tómalas como punto de partida y verifica con una tabla de muestra de dos filas en tu plataforma de destino antes de confiar en ellas.
| Plataforma | :--- (izquierda) | :---: (centro) | ---: (derecha) | colspan / rowspan | Base |
|---|---|---|---|---|---|
| GitHub README / Issue / PR | OK | OK | OK | No (requiere HTML) | documentado (especificación GFM, extensión de tablasSe abre en una pestaña nueva) |
| GitLab | OK | OK | OK | No | documentado (documentación Markdown de GitLabSe abre en una pestaña nueva) |
| Bitbucket | OK | parcial | OK | No | reportado — verifica en tu instancia |
| Notion (al pegar) | OK | se ignora | se ignora | No | reportado — verifica con una prueba de pegado |
| Obsidian | OK | OK | OK | No (requiere HTML) | documentado (ayuda de Obsidian, tablasSe abre en una pestaña nueva) |
| Zenn / Qiita | OK | OK | OK | No | reportado — verifica antes de publicar |
| Vista previa de VS Code | OK | OK | OK | No (HTML funciona en celdas HTML) | documentado (la vista previa integrada usa markdown-it con tablas GFM) |
Si necesitas combinar celdas o un layout complejo, incrusta HTML directamente dentro del Markdown: la mayoría de los renderizadores aceptan un bloque <table> tal cual.
Codificación de caracteres
CSV no es un formato único: el comportamiento cambia según la codificación (UTF-8, UTF-8 con BOM, Windows-1252, ISO-8859-1) y según el separador (coma, punto y coma, tabulador, barra vertical). Dos cosas conviene saber:
- Codificación — CSV a Markdown funciona pegando texto, así que trabaja sobre lo que el navegador ya decodificó. Si tu archivo es UTF-8 (con o sin BOM), abrirlo en cualquier editor moderno y copiarlo funciona. Para archivos guardados en Windows-1252 o ISO-8859-1, ábrelos primero con la codificación correcta (en VS Code, "Reopen with Encoding") y cópialos después — de lo contrario las tildes y la ñ llegan como mojibake.
- Separador — la herramienta detecta automáticamente entre
,,;,|. El caso más habitual en español es el punto y coma que Excel usa al exportar, y está explicado en detalle en la sección siguiente.
Cuando el CSV viene de Excel: separador ; y decimales con coma
Si guardas un libro de Excel como archivo .csv, el separador de lista que se usa por defecto no es siempre la coma. Depende de la configuración regional de Windows: al guardar un libro como CSV, Excel usa el separador de lista definido en la configuración regional, y ese separador se puede cambiar desde la configuración regional de Windows (documentación de Microsoft, importar o exportar archivos de textoSe abre en una pestaña nueva). Microsoft también indica que, cuando el símbolo decimal de la configuración regional es la coma, Excel usa el punto y coma como separador de lista al exportar.
Esto significa que un CSV exportado desde una máquina con configuración regional española, argentina o colombiana puede llegar con ; como separador en lugar de ,. CSV a Markdown detecta automáticamente entre ,, ;, \t y |, así que pegar el archivo tal cual normalmente funciona sin que tengas que cambiar nada.
Lo que no cambia es la coma decimal en sí. Medimos el mismo analizador que usa la herramienta con el formato numérico por defecto de ocho configuraciones regionales, en 2, 3 y 4 columnas (medición reproducible en scripts/benchmarks/spreadsheet-paste-delimiter/): de 48 casos solo fallaron los 9 que combinan separador de miles por coma con números grandes, y la coma decimal por sí sola no alteró la detección en ninguna configuración regional. Esto es un caso distinto al de pegar directamente desde el portapapeles de Excel — para ese escenario (TSV con separador de miles desplazando columnas), consulta Excel o Google Sheets a una tabla Markdown.
Preguntas frecuentes
¿Puedo pegar una columna de Excel directamente sin guardarla como CSV?
Sí. Cuando copias un rango desde Excel o Google Sheets, lo que llega al portapapeles es texto separado por tabulaciones (TSV), no CSV. CSV a Markdown detecta automáticamente el delimitador de tabulación, así que pegar y ejecutar funciona igual. Consulta Excel o Google Sheets a una tabla Markdown para ver el proceso completo.
¿FormatArc sube mi CSV a un servidor?
No. La conversión se ejecuta por completo como JavaScript en la pestaña de tu navegador. No se envía nada a FormatArc ni a ningún servidor de terceros. Si tu CSV contiene datos de clientes, cifras financieras o contenido cubierto por un NDA, la conversión basada en pegar es la única opción segura aparte de ejecutar un script local. Consulta ¿son seguros los conversores JSON online? para la comparativa de privacidad completa entre tipos de herramientas.
¿Por qué mi tabla se ve bien en GitHub pero se rompe en otro sitio?
Lo más probable es que el renderizador no soporte la alineación GFM o la sintaxis de tablas con barras verticales (Notion ignora la alineación en silencio; algunos renderizadores Markdown de CMS esperan CommonMark e ignoran por completo las tablas con barras). Consulta la tabla de arriba, o convierte a HTML con Markdown a HTML para las plataformas que no manejan tablas con barras.
¿Cómo escapo una | dentro de una celda?
Usa \| (barra invertida + barra vertical). El conversor de FormatArc lo hace automáticamente para el CSV pegado que contiene barras verticales. Consulta la tabla Markdown no se renderiza si tu tabla sale rota después de copiar y pegar.
¿Cuál es el tamaño máximo que puedo pegar?
No hay un límite estricto más allá de lo que la pestaña del navegador pueda mantener en memoria. Medimos el mismo código de conversión que se ejecuta en la herramienta (scripts/benchmarks/csv-to-markdown-throughput/, medido el 2026-07-13 en un Apple M5 Pro, Node, mediana de 7 ejecuciones en caliente): un CSV de 10.000 filas se convierte en unos 7 ms, 50.000 filas en unos 36 ms y 100.000 filas (~5 MB) en unos 75 ms — los tiempos en el navegador varían según la máquina, pero la propia conversión no es ni de lejos el cuello de botella. Para CSV muy grandes (cientos de MB), ejecutar un script local con formatarc en npm es más práctico que pegarlo en una pestaña.
Para terminar
Convertir CSV en una tabla Markdown a mano consume tiempo en contar filas, ajustar anchos de columna y escapar caracteres. CSV a Markdown lo hace en tres clics. Pruébalo la próxima vez que te encuentres colocando barras verticales manualmente.
Si necesitas afinar la tabla generada (alineación, barras verticales escapadas, saltos de línea u otros detalles específicos de GFM), consulta Tablas en Markdown: sintaxis, alineación y ejemplos para copiar y pegar para la referencia completa. Para una referencia rápida de la sintaxis, la chuleta de tablas GFM también resulta útil.
Para conocer los fundamentos del propio CSV, consulta Qué es CSV. Para convertir CSV en JSON en su lugar, consulta la guía de CSV a JSON. Si quieres copiar directamente desde Excel o Google Sheets sin pasar por un archivo CSV, consulta Excel o Google Sheets a una tabla Markdown. Si tus datos de origen están en HTML en lugar de CSV (por ejemplo, la tabla de una página web o una exportación de un CMS), consulta la guía de HTML a Markdown. Si necesitas llevar la tabla Markdown resultante un paso más allá hacia HTML (para incrustarla en un CMS que no use Markdown o en un correo HTML), consulta la guía de Markdown a HTML. Si prefieres ejecutar la misma conversión desde la barra de herramientas de tu navegador, consulta la guía de la extensión de Chrome de FormatArc 2026.