Tablas en Markdown: sintaxis de GFM, alineación y límites
Tablas de tuberías de GFM, alineación y límites de celdas.
Una tabla en Markdown se compone de una fila de encabezado, una fila delimitadora de guiones y las filas de datos debajo de ella. La fila delimitadora es la que convierte las barras verticales en una tabla en GFM y en Hugo.
Esta guía forma parte de Herramientas de documentación en 2026: Markdown, LaTeX, PDF y flujos de trabajo de impresión. Los otros tipos de bloques están en la Hoja de referencia de Markdown.
Las tablas no forman parte de la sintaxis original de Markdown ni de CommonMark. Se trata de la extensión de tablas en la especificación de GitHub Flavored Markdown. Hugo 0.164 utiliza Goldmark con dicha extensión activada por defecto (markup.goldmark.extensions.table). Las muestras a continuación están delimitadas por cercas para que las barras verticales permanezcan literales, que es el patrón en Bloques de código en Markdown.
Sintaxis de tablas con barras verticales
Una tabla se compone de tres partes: una fila de encabezado, una fila delimitadora y cero o más filas de datos. Las celdas se separan mediante |. Una barra vertical al inicio y al final de una fila es opcional. Los espacios junto a una barra vertical se recortan.
| Encabezado 1 | Encabezado 2 |
| --- | --- |
| Celda A1 | Celda B1 |
| Celda A2 | Celda B2 |
La documentación de escritura de GitHub indica que cada celda delimitadora necesita al menos tres guiones, y que se requiere una línea en blanco antes de la tabla para que GitHub la renderice. La especificación de GFM describe la celda delimitadora como guiones, con un dos punto opcional en cualquiera de los lados, y sus ejemplos incluyen una celda con un solo guion. Hugo 0.164 renderizó esto como una tabla:
| A | B |
| - | - |
| 1 | 2 |
La misma renderización de Hugo también convirtió una tabla en un <table> cuando la línea anterior era un párrafo y no había una línea en blanco. En GitHub, sigue el delimitador de tres guiones y la línea en blanco. En este sitio, un guion es suficiente y la línea en blanco no es necesaria.
|Demasiado|Ajustado| con un delimitador |---|---| también se renderizó. Los espacios junto a las barras verticales se recortan. Los espacios en el primer ejemplo mantienen legible la diferencia de código fuente.
La fila de encabezado y la fila delimitadora deben tener el mismo número de celdas. Si difieren, Hugo no reconoce una tabla. Esto permanece como texto ordinario, y los guiones son entonces elegibles para el tipógrafo de Hugo:
| abc | def |
| --- |
| bar |
Una fila de datos puede ser más corta o más larga que el encabezado. Una fila corta se rellena con celdas vacías. Las celdas que exceden el número del encabezado se descartan.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
La primera de estas renderiza una tercera celda en blanco. La segunda renderiza solo 1 y 2.
Una línea sin barras verticales sigue estando dentro de la tabla hasta una línea en blanco. Hugo 0.164 colocó un bar posterior en la tabla como una fila con una segunda celda vacía, coincidiendo con el ejemplo 202 de GFM. El siguiente párrafo comienza después de la línea en blanco.
| abc | def |
| --- | --- |
| bar | baz |
bar
siguiente
Alineación de columnas
La alineación es un dos puntos en la fila delimitadora. --- sin dos puntos es alineación a la izquierda, lo mismo que :---.
| Izquierda | Derecha | Centro |
| :--- | ----: | :----: |
| texto | 12,50 | sí |
| Izquierda | Derecha | Centro |
|---|---|---|
| texto | 12,50 | sí |
Los dos puntos en la fila de encabezado son caracteres en esa celda. No configuran la alineación. La fila delimitadora siguiente es la que Hugo usó:
| :--- Izquierda | Derecha ---: |
| :-------- | ---------- |
| Correcto | Alineación |
Contenido de celda
Los elementos en línea funcionan dentro de una celda: énfasis, segmentos de código y enlaces. Las estructuras de bloque no lo hacen. La especificación de GFM dice que no se pueden insertar elementos de nivel de bloque en una tabla, por lo que una lista o un bloque delimitado dentro de una celda no es una lista ni una cerca.
| Función | Estado | Documentación |
| ---------- | ---------- | ------------- |
| **API v2** | *Publicada*| [Docs](/api) |
| `Auth` | Beta | Próximamente |
Una barra vertical literal es \| o |. Hugo 0.164 renderizó ambos como |.
| Expresión | Resultado |
| ---------- | --------- |
| a | b | true |
| x \| y | false |
Un salto de línea dentro de una celda es una etiqueta HTML <br>. Este sitio establece markup.goldmark.renderer.unsafe en verdadero, por lo que esa etiqueta se conserva. Un procesador que elimina el HTML crudo concatena las dos mitades.
Tres guiones escritos como texto de celda son otra trampa en Hugo. El tipógrafo reescribe --- en una celda como un guion largo (—). Un segmento de código conserva los guiones. \--- se renderizó como -–.
| Como texto | Como código |
| ---------- | ----------- |
| --- | `---` |
Celdas combinadas
GFM no tiene rowspan ni colspan. Cuando una celda debe abarcar dos filas, la tabla es HTML. El renderizador no seguro de este sitio deja ese HTML en la página:
<table>
<tr>
<td rowspan="2">Combinado</td>
<td>Celda 1</td>
</tr>
<tr>
<td>Celda 2</td>
</tr>
</table>
El escritor markdown+pipe_tables de Pandoc emite la sintaxis de barras verticales en esta página. Ese es el escritor usado al convertir documentos de Word a Markdown. Las tablas de rejilla y otros diseños exclusivos de Pandoc son funciones del dialecto, cubiertas en GFM vs CommonMark vs Pandoc Markdown.
Una tabla de barras verticales ancha se desplaza o se desborda. Las reducciones portátiles son un diseño transpuesto, varias tablas más pequeñas, o una tabla HTML con su propio CSS. La sintaxis de barras verticales no tiene pie de tabla. El índice de contenido de Hugo se construye a partir de los encabezados.
Comprobaciones cuando una tabla se mantiene como texto
Cuenta las celdas en la fila de encabezado y la fila delimitadora. Si esas dos cuentas difieren, el bloque es un párrafo. Una fila de datos corta sigue siendo una tabla, con una celda vacía al final. La regla MD056 de markdownlint pide que cada fila coincida con esa cuenta de todos modos, porque una fila corta parece una celda faltante y una celda extra se descarta.
Mira la fila delimitadora por los dos puntos. Un dos puntos situado en el encabezado es texto, y la columna se mantiene con la alineación del delimitador.
Si --- dentro de una celda aparece como un solo glifo de guion en este sitio, el tipógrafo lo reescribió. Pon los guiones en un segmento de código.
Si GitHub muestra las barras verticales como texto, añade la línea en blanco que la documentación de GitHub requiere y usa al menos tres guiones en cada celda delimitadora. Hugo 0.164 ya aceptó la forma más corta.
Una fila delimitadora faltante es la otra manera en que un bloque de barras verticales se mantiene como texto. Hugo 0.164 dejó esto como un párrafo:
| Encabezado 1 | Encabezado 2 |
| Celda A | Celda B |
Una tabla de parámetros
La misma fila delimitadora lleva la alineación y deja espacio para código en línea:
| Parámetro | Tipo | Predeterminado | Obligatorio |
| :-------- | :----- | :-----: | :------: |
| `apiKey` | string | — | Sí |
| `timeout` | number | 30000 | No |
| `retries` | number | 3 | No |
