Tablas de Markdown vs HTML: cuándo cambiar

La contrapartida en un párrafo

Las tablas de Markdown son más fáciles de leer y escribir en el origen. Las tablas HTML pueden expresar cosas que Markdown no. Para el 90 % de las tablas (texto, alineación simple, sin celdas combinadas), Markdown es la mejor herramienta. Para el 10 % restante, baja a HTML dentro del documento Markdown.

Lo que las tablas de Markdown no pueden hacer

1. Combinación de filas. Una celda que abarca dos filas. Markdown no tiene sintaxis para esto.
2. Combinación de columnas. Un encabezado que abarca dos columnas. Markdown no tiene sintaxis para esto.
3. Alineación por celda. La alineación de Markdown se fija por columna. Si la celda «Fecha» de la fila 1 va a la derecha pero la de la fila 2 necesita ir a la izquierda por algún motivo, Markdown no puede expresarlo.
4. Estilos de celda en línea. Colores de fondo, grosores de fuente, bordes personalizados. Markdown no tiene el concepto de estilo.
5. Filas de pie. Markdown no tiene un equivalente de <tfoot>. Algunos motores infieren una a partir de la sintaxis de la última fila, pero no es estándar.
6. Leyendas. El elemento <caption> no existe en Markdown. Usa un párrafo encima de la tabla en su lugar.
7. Encabezados en el lado izquierdo. Una tabla donde la primera columna es en sí un encabezado (el patrón <th scope="row">). El encabezado de Markdown siempre es la fila superior.

Si tu tabla necesita alguna de estas, baja a HTML.

Lo que las tablas HTML pierden

El costo es la verbosidad. La misma tabla en Markdown:

| Name  | Role     |
|:------|:---------|
| Alice | Engineer |
| Bob   | Designer |

Y en HTML:

<table>
  <thead>
    <tr><th>Name</th><th>Role</th></tr>
  </thead>
  <tbody>
    <tr><td>Alice</td><td>Engineer</td></tr>
    <tr><td>Bob</td><td>Designer</td></tr>
  </tbody>
</table>

Cinco veces más caracteres. Tres veces el ruido visual en el origen. Para una tabla diminuta esto está bien; para una tabla de 30 filas es una carga de mantenimiento.

El árbol de decisión

Cinco preguntas, en orden. Detente en el primer «sí»:

1. ¿Necesitas combinar filas o columnas? Si la respuesta es sí, HTML.
2. ¿Necesitas estilo por celda (colores, grosores, bordes)? Si la respuesta es sí, HTML.
3. ¿Esto se va a renderizar en un entorno de Markdown que elimina el HTML (Reddit, Discord, Stack Overflow)? Si la respuesta es sí, Markdown. Busca una forma de expresar los datos sin la función exclusiva de HTML.
4. ¿La tabla va a crecer más allá de 20 filas? Si la respuesta es sí, Markdown. La legibilidad del origen importa más que las funciones de estilo.
5. Si no: Markdown.

Incrustar HTML dentro de Markdown — el flujo de trabajo

La mayoría de los entornos de Markdown (GitHub, GitLab, Notion, Obsidian, MkDocs, Docusaurus, MDX) dejan pasar el HTML en crudo dentro de un documento Markdown. El patrón:

# My document

Some markdown text here.

<table>
  <thead>
    <tr><th rowspan="2">Item</th><th colspan="2">Q1</th></tr>
    <tr><th>Plan</th><th>Actual</th></tr>
  </thead>
  <tbody>
    <tr><td>Revenue</td><td>$100k</td><td>$112k</td></tr>
  </tbody>
</table>

More markdown after the table.

El bloque de HTML no se interpreta como Markdown. Todo lo que está dentro se queda como HTML en crudo. El formato de Markdown a su alrededor funciona con normalidad.

Dos notas prácticas:

• La mayoría de los motores de Markdown requieren una línea en blanco antes y después del bloque de HTML.
• Dentro del HTML, el formato de Markdown no funciona. No puedes usar **bold** dentro de una celda HTML. Escribe <strong>bold</strong> en su lugar.

El patrón de estilo con HTML y contenido en Markdown

Para los sitios de documentación con paso de compilación (MkDocs, Docusaurus, Astro), hay una tercera opción: define la estructura de la tabla en Markdown y aplica el estilo con CSS apuntando al HTML renderizado. Esto mantiene el origen limpio y deja que un solo archivo CSS dé estilo a todas las tablas de forma consistente. La contrapartida es que solo funciona en entornos con paso de compilación. No ayuda en GitHub, Reddit ni en ningún otro sitio donde el Markdown se renderice sin tu CSS.

Las tres reglas generales

1. Usa Markdown por defecto. Más fácil de leer, más fácil de mantener, funciona en todas partes donde funcione Markdown.
2. Baja a HTML cuando la estructura de datos lo exija. Combinaciones, alineación compleja o estilos que no puedes lograr de otra forma.
3. No mezcles sin necesidad. Si empiezas una tabla en HTML, mantenla en HTML. El cambio de modo a mitad de la tabla es donde los analizadores se rompen.

Para la referencia completa de las tablas de Markdown, mira la guía completa de las tablas de Markdown. Para la hoja de referencia imprimible, mira la hoja de referencia de tablas de Markdown.