Un README resulta cómodo para revisar un proyecto, pero esa misma información puede necesitar un documento estable para una reunión, una entrega o un archivo. Convertir Markdown a PDF permite conservar una fuente de texto plano y entregar una copia con páginas, márgenes y texto seleccionable. La tarea no termina al obtener un archivo con extensión .pdf: hay que comprobar que la estructura, los enlaces, las tablas y el código siguen comunicando lo previsto después de paginar.
Esta guía construye un README reproducible y lo convierte con la herramienta Markdown a PDF. UtilX procesa la entrada en el navegador y solo exporta cuando se solicita. El ejemplo no contiene información confidencial y distingue claramente lo que demuestra la vista previa de lo que debe comprobarse en el PDF.
Definir el documento antes de darle formato
Markdown describe estructura mediante convenciones de texto. CommonMark distingue bloques como títulos, párrafos, citas, listas, separadores y bloques de código de elementos en línea como enlaces, énfasis y código. GitHub Flavored Markdown añade tablas, tareas y tachado. El conversor traduce esas estructuras a un modelo de páginas; no puede conservar exactamente el ancho fluido del navegador.
Primero define propósito y lector. En este ejemplo, un equipo necesita una lista de control de publicación que pueda consultar sin conexión. El PDF debe leerse en papel A4, conservar enlaces HTTPS pulsables, mostrar el código como código y diferenciar tareas terminadas. Son requisitos verificables. “Se ve idéntico en todas partes” no lo es: la vista previa y el PDF utilizan motores de composición distintos, por lo que pueden variar saltos de línea y página.
Un README completo de ejemplo
Crea release-readme.md con el siguiente contenido sintético. Recorre la sintaxis admitida sin depender de archivos remotos:
# Publicación de Atlas 1.4
**Responsable:** equipo de documentación
*Ventana:* 18 de septiembre de 2026
~~Objetivo anterior: 1.3~~
> Publicar solo si supera la comprobación de reversión.
## Lista
- [x] Congelar traducciones
- [ ] Publicar paquete
- [x] Verificar checksum
- [ ] Copiar nota de versión
## Comandos
Ejecuta `npm test` y después:
~~~sh
npm run build
npm run smoke
~~~
## Entornos
| Nombre | URL | Responsable |
| --- | --- | --- |
| Pruebas | [estado](https://example.com/status) | Plataforma |
| Producción | pendiente | Operaciones |
---
Consulta el [procedimiento](https://example.com/runbook).
El resultado esperado incluye un título principal, tres metadatos —responsable, ventana y objetivo anterior tachado—, una cita, tareas anidadas, código en línea y en bloque, una tabla de tres columnas, un separador y dos enlaces. No se fija un número de páginas: depende del papel, los márgenes, el tamaño de letra y los ajustes de línea.
Convertir y verificar paso a paso
Abre la herramienta localizada y pega el ejemplo o importa el archivo .md. Mantén la fuente por debajo de 200 KiB en UTF-8; una entrada mayor se rechaza antes de analizarse. En la vista previa revisa la jerarquía, no los límites de página. Confirma que el título destaca sobre el cuerpo, que las tareas abiertas y terminadas se distinguen, que cada elemento anidado sigue bajo su padre y que la tabla conserva tres columnas.
Elige A4, márgenes de 20 mm, texto de 12 pt y numeración. Escribe un nombre claro, como atlas-1-4-publicacion.pdf, y exporta de forma explícita. Cambiar el texto no debe iniciar descargas. Abre el PDF guardado en otro lector. Selecciona y copia una frase para comprobar que el cuerpo es texto y no una captura. Busca reversión, activa los dos enlaces HTTPS y amplía el bloque de comandos y la tabla.
Repite una vez con Letter si el destinatario imprime en ese formato. Compara significado y legibilidad, no coordenadas. Una tabla estrecha puede ajustar de otra manera y un título puede pasar a la página siguiente. Si una fila queda confusa, acorta sus celdas o conviértela en lista antes de reducir todo el documento.
Qué cambia realmente cada opción
A4 y Letter tienen dimensiones distintas, así que un mismo párrafo puede ocupar diferente número de líneas. Los márgenes de 12, 20 y 28 mm modifican el área de escritura. Los cuerpos de 10, 12 y 14 pt cambian densidad y facilidad de lectura. Las opciones se combinan: aumentar margen y letra produce saltos anteriores y normalmente más páginas.
Los números de página son un elemento opcional de la salida, útil para comentar una copia fija, pero no forman parte de Markdown. El generador distribuye el contenido en un tamaño cerrado y puede añadir el número dinámico al pie. El PDF mantiene texto seleccionable y los enlaces compatibles. La vista previa representa con honestidad estilo y orden; no garantiza la misma paginación.
La primera versión admite títulos, párrafos, negrita, cursiva, tachado, enlaces HTTP(S) y mailto, listas ordenadas o no ordenadas anidadas, tareas, citas, separadores, código en línea y cercado y tablas GFM. Conviene enumerarlo porque existen varios dialectos: que una extensión funcione en un repositorio no implica que todos los conversores la entiendan.
Resolver fallos frecuentes
Si una lista pierde el anidado, revisa sangría y líneas en blanco entre bloques. Si una tabla aparece como tuberías literales, comprueba que tenga cabecera, fila delimitadora y las mismas columnas lógicas en cada fila. Si el código absorbe texto posterior, cierra la valla con el mismo carácter y al menos la longitud de apertura. Estas comprobaciones siguen las reglas de bloques, no el espaciado visual de un editor concreto.
Las imágenes remotas y referencias a archivos locales no se cargan. El conversor muestra su texto alternativo y una advertencia para que la omisión sea visible. Escribe un alt útil y adjunta las imágenes aprobadas por separado si el flujo final las exige. El HTML crudo aparece como texto literal con aviso y nunca se ejecuta. No uses etiquetas HTML para sortear una limitación de diseño.
Si se detiene la exportación, comprueba primero el tamaño UTF-8. Dividir un documento grande en capítulos coherentes es más seguro que borrar código o avisos. Si falla un enlace, confirma que comienza por https://, http:// o mailto: y pruébalo tanto en la vista previa como en el PDF exportado.
Decisiones para una entrega duradera
Conserva Markdown como fuente editable y considera el PDF una salida fechada. Registra papel, margen, cuerpo, numeración y fecha de la herramienta junto al proceso. Otro revisor podrá reproducir la exportación en vez de editar un PDF opaco. Para documentos controlados, guarda juntos la revisión de la fuente y el archivo exportado.
Ordena los títulos y escribe enlaces descriptivos. No dependas solo del color para mostrar el estado de una tarea. Mantén cortas las líneas de código y compactas las tablas: ambas estructuras tienen un ancho natural difícil de encajar en papel. Una lista suele resistir mejor que una tabla llena de párrafos. Antes de compartir, lee el PDF a zoom normal y usando selección o búsqueda, no solo miniaturas.
El procesamiento en el navegador evita que esta conversión necesite enviar el Markdown introducido al servidor de la aplicación, pero la descarga entra en el flujo normal de almacenamiento del navegador y el sistema. Aplica las reglas de clasificación y distribución habituales.
Límites del conversor
La primera versión no representa fórmulas matemáticas, diagramas Mermaid, HTML personalizado ni contenido ejecutable. No obtiene imágenes remotas o archivos locales. Tampoco promete igualdad de píxel o paginación entre vista y PDF, conformidad de archivo, accesibilidad de PDF etiquetado, firmas, cifrado ni compatibilidad con complementos propios de un repositorio. Que un PDF se abra no demuestra que sea accesible, aprobado o completo.
Una tabla compleja puede seguir siendo difícil de leer aunque sea válida. Para evitar recortes, la sangría del PDF deja de aumentar después de seis niveles de lista anidada, aunque conserva el contenido restante. Si el ancho disponible dejara una columna por debajo de 25 pt, la tabla se rechaza con un aviso: divide columnas o reduce los márgenes en lugar de forzar una salida ilegible.
Las cadenas sin cortes y las líneas largas de código pueden ajustarse de forma extraña. La exportación añade puntos de ajuste y algunos lectores PDF pueden insertar espacios al copiar texto que cruza esos puntos. Si un comando debe ser exacto, cópialo desde el PDF y compáralo carácter por carácter con la fuente Markdown antes de ejecutarlo. Los lectores también difieren al activar enlaces o mostrar fuentes. Prueba el archivo exportado en el entorno de uso y recurre a publicación especializada si necesitas tipografía exacta, accesibilidad avanzada o cumplimiento normativo.
Lista final de comprobación
Confirma que la fuente usa UTF-8 y no supera 200 KiB. Revisa títulos, énfasis, tachado, enlaces, listas anidadas y de tareas, citas, separadores, código y tablas frente al significado previsto. Atiende cada advertencia de imagen y HTML literal. Exporta con A4 o Letter, márgenes de 12, 20 o 28 mm, cuerpo de 10, 12 o 14 pt y la opción de numeración acordada.
Abre por separado el PDF descargado. Selecciona y copia texto, busca una frase conocida, sigue los enlaces importantes e inspecciona columnas, código y transiciones de página. Compara contenido y jerarquía con el README sin exigir paginación idéntica a la vista previa. Conserva finalmente la fuente y las opciones junto al PDF verificado para que otra persona pueda repetir el resultado.
Fuentes: especificación CommonMark, especificación GitHub Flavored Markdown y documentación de definición de documentos de pdfmake.