Tablas Markdown a PDF: cómo encajar tablas anchas en la página

Una tabla es de lo primero que busca un lector en documentación técnica. Y también de lo primero que se rompe al convertir Markdown a PDF. Columnas legibles en un monitor ancho quedan apiñadas en A4, celdas extensas desbordan los márgenes y las filas se dividen entre páginas de modo que el encabezado pierde sentido.

md2pdf renderiza tablas de GitHub-flavored Markdown y transfiere el resultado a la hoja de estilo de impresión o, en libros, al renderizador A4 PDF. La herramienta mantiene legible una tabla razonable, pero no puede crear espacio donde no lo hay. La clave radica en el Markdown fuente: elegir columnas adecuadas y mantener celdas breves.

Esta guía aborda primero el diseño del documento fuente y después las revisiones de impresión para detectar problemas. Para el flujo general, consulte Cómo convertir un README de GitHub a PDF.

Por qué las tablas fallan al imprimir

En un navegador una tabla es flexible: desborda el contenedor o permite desplazamiento lateral. En papel, el ancho es estricto y no existen barras de desplazamiento. Si el contenido supera la página, el motor recorta la tabla o la encoge a tamaños ilegibles.

Tres hábitos agravan este problema:

• Demasiadas columnas. Ocho columnas estrechas son más difíciles de leer que cuatro bien proporcionadas.
• Párrafos extensos en celdas. Una celda con varias oraciones convierte una cuadrícula ágil en un bloque pesado.
• Código o URLs indivisibles. Un término extenso sin espacios fija el ancho mínimo de toda la columna.

La solución no es reducir el tamaño de letra, sino diseñar tablas con propósitos acotados.

Empiece con una tabla que quepa de forma natural

Una tabla eficaz responde a un único propósito y contiene pocas columnas. El siguiente ejemplo compara temas de impresión sin intentar documentar cada propiedad CSS:

| Setting | Clean | Business | Academic |
| --- | :--- | :--- | ---: |
| Body type | Sans | Serif | Justified serif |
| Best for | Specs | Reports | Course readers |
| Tone | Neutral | Formal | Editorial |

Esta tabla se adapta cómodamente a formatos A4 y Letter, y resiste bien la traducción gracias a sus celdas breves. Los indicadores de alineación facilitan la lectura en el código fuente: :--- izquierda, :---: centro y ---: derecha.

Utilice la alineación con sentido práctico: números a la derecha y etiquetas cortas a la izquierda. El centrado rara vez resulta necesario.

Defina columnas según la pregunta, no según todos los datos

Antes de añadir una columna, reflexione sobre qué pregunta responde la tabla. Una tabla de migración responde ‘¿qué cambia y qué debo hacer?’. Eso genera tres columnas: elemento, cambio y acción. Un volcado de base de datos con doce campos no pertenece a un PDF.

Un buen criterio consiste en leer los encabezados en voz alta. Si no forman una oración coherente o una comparación limpia, la tabla contiene demasiada información.

Para datos de referencia amplios, considere una lista de definiciones de dos columnas:

| Field | Meaning |
| --- | --- |
| `owner` | GitHub user or organization |
| `repo` | Repository name without the host |
| `ref` | Branch, tag, or commit SHA |

Este formato imprime con mayor limpieza y se traduce con más facilidad que una matriz de múltiples columnas.

Mantenga las celdas breves y fáciles de escanear

Las tablas sirven para contrastar datos, no para redactar explicaciones extensas. Si una celda requiere más de dos frases, traslade la explicación al texto inferior y deje un resumen breve en la cuadrícula.

Pautas recomendadas:

1. Use frases concisas. ‘Requiere repositorio público’ es suficiente.
2. Sitúe las unidades en el encabezado. Escriba Tamaño (MB) una sola vez.
3. Evite saltos forzados en celdas. La etiqueta <br> complica la paginación.
4. Emplee enlaces cortos. Enlace una etiqueta breve en lugar de una URL completa.
5. No dependa exclusivamente de colores. Los documentos pueden imprimirse en escala de grises.

Si una celda debe incluir un comando extenso, colóquelo en un bloque de código debajo de la tabla y menciónelo por su nombre.

Gestione datos anchos antes de exportar

Cuando una tabla es inevitablemente extensa y no puede prescindir de columnas, altere la estructura del documento:

• Segmente por audiencia. Las necesidades de los administradores difieren de las de los desarrolladores.
• Divida cronológicamente. Los historiales extensos pueden separarse por versiones principales.
• Transponga la información. Si hay muchos atributos y pocos elementos, coloque atributos en filas y elementos en columnas.
• Transforme a lista. Si abundan las celdas vacías, una lista con subtítulos resulta más clara.

Tras reestructurar, revise nuevamente que no existan URLs largas sin separar que ensanchen la columna.

Compruebe la paginación y encabezados repetidos

Una tabla que encaja en una sola página puede fallar cuando se extiende a dos. Los encabezados deben repetirse, las filas no deben partirse a mitad de texto y la tabla no debe comenzar al pie de una página con una sola fila huérfana.

El motor de impresión del navegador y el renderizador de libros gestionan el salto de página de forma independiente. Si una tabla abarca varias páginas, añada una breve leyenda introductoria que nombre las columnas para mantener el contexto del lector.

Lista de comprobación previa a la exportación

Antes de imprimir o exportar, verifique los siguientes aspectos clave:

• La tabla responde a un propósito claro y no supera cinco o seis columnas.
• Cada encabezado es conciso e incluye su unidad de medida.
• Las celdas contienen síntesis breves en lugar de párrafos.
• No hay URLs completas ni términos indivisibles más anchos que la página.
• La alineación se aplica estratégicamente en números y etiquetas breves.
• La tabla cuenta con título o pie explicativo si se divide en varias páginas.
• Ha comprobado el archivo PDF final, no solo la vista previa en pantalla.

Para particularidades de cada tema visual, consulte Clean vs Business vs Academic vs Dark.

Una tabla no necesita ornamentos: su valor reside en ser legible tras abandonar el navegador. Una tabla contenida y clara siempre superará a una cuadrícula abarrotada.