7 casos de uso prácticos para convertir un README en PDF

Un enlace a un repositorio es una buena forma de compartir documentación con alguien que ya vive en GitHub. Es una mala forma de compartir documentación con todos los demás. Los revisores pierden contexto, los clientes no quieren crear una cuenta y una URL no es un archivo. Un PDF resuelve el problema de distribución, pero solo si se produce con intención.

md2pdf gira en torno a un flujo acotado: obtener Markdown de un repositorio público, de un archivo local o del portapapeles; renderizarlo con Markdown al estilo GitHub; aplicar una hoja de estilos de impresión; y enviarlo al diálogo «Guardar como PDF» del navegador. Esa estrechez es útil. Significa que la misma herramienta puede servir para una entrega a cliente de cinco páginas y para una lectura de curso de cincuenta, sin servidor, cuenta ni subidas.

A continuación, siete situaciones en las que ese flujo se gana su lugar, con los ajustes y la preparación que hacen funcionar cada una.

1. Entregas a clientes y partes interesadas

Un cliente rara vez quiere acceso al repositorio solo para leer un resumen del proyecto. Quiere un documento que pueda abrir, reenviar a un colega y anotar en una reunión. Un PDF de README suele tener el nivel de detalle adecuado: alcance, notas de arquitectura, pasos de configuración, capturas de pantalla y limitaciones conocidas en un solo archivo.

Configuración recomendada:

• Tema: Business para públicos externos, Clean para un cliente muy técnico.
• Tabla de contenidos: activada para cualquier documento de más de cuatro páginas.
• Tamaño de página: el de la región del cliente: A4 para la mayor parte de Europa y Asia, Carta para Estados Unidos y Canadá.
• Origen: obtén el repositorio si es público; si no, pega el Markdown o sube el archivo README.

Preparación que importa:

• Elimina los enlaces a tickets internos, las URL de staging y las credenciales antes de exportar. La herramienta no sube el documento, pero el PDF sigue siendo un archivo que se puede reenviar.
• Sustituye las rutas de imagen relativas por rutas del repositorio que existan de verdad. md2pdf las resuelve durante la obtención de un repositorio, pero una imagen de origen rota seguirá rota en el PDF.
• Comprueba que el README empieza con un resumen, no con un registro de cambios. Un documento de entrega debe decirle al lector qué es el proyecto antes de decirle qué cambió.
• Añade un párrafo breve de «Cómo leer este documento» si el README mezcla instrucciones de configuración con antecedentes de arquitectura.

Usa la opción de numeración de páginas del navegador si el cliente va a referirse a páginas concretas durante la revisión. La hoja de estilos de impresión de la aplicación no añade números de página por sí sola; los encabezados y pies de página del navegador son la forma más sencilla de conseguirlos.

2. Archivos sin conexión y documentación de versiones

La documentación que solo vive en un repositorio cambia bajo los pies del lector. Cuando necesitas una instantánea de cómo era una versión en un momento dado, un PDF es un artefacto estable. Se puede guardar junto a un binario, adjuntar a un registro de versión o conservar en el archivo de un proyecto sin preocuparte por una futura reescritura del README.

Configuración recomendada:

• Tema: Clean.
• Tabla de contenidos: activada.
• Nombre de archivo: incluye el repositorio, la etiqueta de versión o el commit, y la fecha; por ejemplo, acme-api-v2.4.0-readme-2026-10-02.pdf.
• Origen: obtén el repositorio público y luego confirma que exportas el README que pretendes. La aplicación lee la rama predeterminada, así que usa la vía de pegado si necesitas una etiqueta o un commit fijados.

Preparación que importa:

• Registra el origen en algún lugar del documento o en el nombre del archivo. Un PDF sin versión es solo otro adjunto sin fecha.
• Comprueba los enlaces antes de archivar. Un enlace blob sigue apuntando a la rama predeterminada del repositorio. Si necesitas una instantánea real de una etiqueta o un commit, pega esa versión del README en lugar de usar el flujo de obtención, y anota el hash del commit en una línea al pie o en el registro de versión que lo acompañe.
• Desactiva los encabezados y pies de página del navegador si incluyen una ruta de archivo local o un nombre de host interno. Quieres que el archivo sea autocontenido, no que filtre la máquina que lo produjo.
• Conserva el Markdown de origen junto al PDF si el archivo debe poder reproducirse. El PDF es el artefacto; el Markdown es la receta.

También es un buen caso de uso para el tema Dark durante la revisión: lee la vista previa en pantalla y luego exporta sabiendo que la hoja de estilos de impresión lo aclarará para papel. Eso sí, revisa el PDF final en lugar de dar por hecho que la apariencia en pantalla es lo que recibirá la impresora.

3. Entregas académicas y dosieres de curso

Estudiantes y docentes suelen tener apuntes en Markdown, documentación de proyectos o paquetes de lectura que deben entregarse o distribuirse como un único documento. Academic tiene una función distinta de la de un README de producto: necesita prosa generosa, bloques de código contenidos y un diseño que no parezca una landing page.

Configuración recomendada:

• Tema: Academic.
• Tabla de contenidos: activada para cualquier documento con más de tres secciones.
• Tamaño de página: sigue el requisito de la institución. A4 es habitual fuera de Estados Unidos; Carta es habitual en Estados Unidos.
• Origen: sube o pega el Markdown si el trabajo no es público. Nunca pongas trabajo no publicado en un repositorio público solo para convertirlo.

Preparación que importa:

• Revisa la jerarquía de encabezados antes de exportar. Una lectura de curso con niveles saltados produce una tabla de contenidos confusa.
• Academic justifica el cuerpo de texto. Las URL muy largas, los identificadores de código y las ecuaciones pueden crear un espaciado incómodo. Divide las URL largas en enlaces de estilo referencia o llévalas a una sección tipo notas al pie.
• Mantén los bloques de código cortos. El tema usa un fondo de código claro que se imprime bien, pero una línea de 120 caracteres seguirá desbordando la página.
• Si el documento incluye citas, mantenlas en el Markdown como sección de referencias. md2pdf renderiza el texto; no gestiona un estilo de cita.
• Imprime un borrador antes de entregar. El texto justificado y la tipografía serif pueden verse distintos en papel que en la vista previa.

Como la conversión ocurre en el navegador, los apuntes no publicados y los borradores de artículos no salen de él. Es una ventaja importante frente a un servicio de «pega tu documento en nuestro convertidor».

4. Paquetes de revisión interna y notas de versión

Los equipos de ingeniería suelen necesitar un único documento para una revisión de diseño, una comprobación de preparación para el lanzamiento o un seguimiento posterior a un incidente. Puede que el origen ya exista como README o como página de documentación. Convertirlo en PDF crea un orden del día fijo para la reunión y un registro de lo que vieron los revisores.

Configuración recomendada:

• Tema: Clean para revisiones de ingeniería, Business para un público de varias áreas.
• Tabla de contenidos: activada.
• Origen: obtención de un repositorio público, o pega el Markdown si el repositorio es privado.

Preparación que importa:

• Pon la decisión o la petición al principio. Un paquete de revisión que empieza con tres páginas de antecedentes no se revisará.
• Marca explícitamente las preguntas abiertas. El formato PDF facilita anotar una copia impresa, pero solo si las preguntas son visibles.
• Elimina secretos e identificadores de clientes. La herramienta no envía el documento a ningún sitio, pero los paquetes de revisión tienden a reenviarse.
• Incluye el commit o la versión del documento en el nombre del archivo. Las notas de revisión sin versión son difíciles de conciliar después.
• Si el documento incluye listas de tareas, comprueba cómo se renderizan. Las listas de tareas de Markdown al estilo GitHub son compatibles, pero una lista de comprobación larga puede partirse entre páginas. Mantén juntos los elementos relacionados.

El flujo de obtención no admite repositorios privados. Para trabajo interno, la vía de pegado o subida es la opción práctica. No es un apaño añadido al producto; es la forma prevista de manejar material que no debería leerse desde una URL pública.

5. Folletos de taller y materiales de conferencia

Un ejercicio de taller que vive en un repositorio da por hecho que hay acceso a la red, una cuenta de GitHub y un portátil que funciona. Un folleto impreso no da por hecho nada de eso. Para un tutorial, una sesión de conferencia o una práctica de aula, un PDF suele ser la copia más fiable en la sala.

Configuración recomendada:

• Tema: Business para un folleto cuidado, Clean para una práctica con mucho código.
• Tabla de contenidos: activada si el folleto tiene varios ejercicios.
• Tamaño de página: el de la impresora del lugar. A4 y Carta son habituales; compruébalo antes de imprimir cincuenta copias.
• Origen: obtención del repositorio para un repositorio público de taller, o subida para un borrador privado.

Preparación que importa:

• Diseña para escala de grises. Un tema que depende solo del color para distinguir secciones perderá esa distinción en una impresora en blanco y negro.
• Mantén las líneas de código por debajo de unos 80 caracteres. Un folleto se lee a la distancia del brazo, no en un monitor de 27 pulgadas.
• Añade una URL corta o un código QR al repositorio activo si los lectores necesitan la versión más reciente. El PDF es la copia estable; el repositorio es la que sigue viva.
• Comprueba el número de páginas. Un folleto de 40 páginas es un artefacto distinto de una hoja de ejercicios de 6 páginas. Usa la tabla de contenidos y los encabezados para decidir qué entra.
• Imprime una copia antes del evento. Los ajustes de impresión del navegador que se veían bien en pantalla pueden producir márgenes distintos en la impresora del lugar.

La hoja de estilos de impresión de la aplicación está diseñada para una paginación limpia, pero no puede saber cómo gestiona los márgenes una impresora concreta. Una impresión de prueba sigue siendo la mejor comprobación de calidad.

6. Solicitudes de subvención, portafolios y candidaturas

Las candidaturas suelen pedir un resumen del proyecto, un texto técnico o una muestra de portafolio como un único adjunto. Un PDF de README puede funcionar bien aquí porque muestra la documentación del propio proyecto en un formato que un revisor puede abrir sin cuenta de GitHub.

Configuración recomendada:

• Tema: Business para un público general, Academic para una candidatura orientada a la investigación.
• Tabla de contenidos: activada si el documento tiene más de unas pocas páginas.
• Tamaño de página: sigue las instrucciones de la candidatura.
• Origen: obtención de un repositorio público, o pega el Markdown si el proyecto es privado.

Preparación que importa:

• Pon primero el proyecto más relevante. Puede que quien revisa la candidatura solo lea las dos primeras páginas.
• Elimina las insignias que no aportan significado. Un muro de insignias de compilación es ruido en un anexo de portafolio.
• Asegúrate de que las capturas de pantalla y los diagramas tienen texto alternativo y aparecen de verdad. Una imagen rota es peor que ninguna imagen.
• Comprueba que los enlaces se pueden pulsar en el PDF. Un revisor que no puede ir al proyecto activo pierde contexto.
• Mantén un tamaño de archivo razonable. Los PDF muy pesados por las imágenes pueden superar los límites de subida de los portales de candidaturas.

También es un caso en el que la tipografía serif del tema Business puede ayudar a que un proyecto técnico se lea como un documento profesional y no como un volcado de repositorio. El contenido sigue teniendo que sostener la candidatura; el tema solo establece el registro.

7. Instantáneas de auditoría y cumplimiento

A veces el objetivo del PDF no es que se lea de principio a fin. Es demostrar qué decía la documentación en una fecha determinada. Un README que describe controles de acceso, tratamiento de datos o procedimientos operativos puede ser una parte útil de un paquete de auditoría cuando se captura como un artefacto inmutable.

Configuración recomendada:

• Tema: Clean.
• Tabla de contenidos: activada para documentos largos.
• Nombre de archivo: incluye el repositorio, el commit y la fecha de captura.
• Origen: obtén el repositorio público, o pega exactamente el Markdown revisado.

Preparación que importa:

• Captura la versión de origen. Un PDF sin referencia de commit es una prueba débil porque el README subyacente puede cambiar.
• No trates el PDF como un sistema de registro. Es una instantánea de la documentación, no un sustituto de registros, políticas o certificaciones firmadas.
• Comprueba que el documento no incluye secretos, nombres de host internos ni datos personales. Un paquete de auditoría suele compartirse más ampliamente que el repositorio original.
• Conserva juntos el Markdown de origen y el PDF. Si alguien cuestiona la captura, el origen explica cómo se produjo el artefacto.
• Vuelve a exportar cuando cambie el origen. Un PDF desactualizado con un nombre de archivo actual es peor que uno obviamente fechado.

Cuándo el PDF es el formato equivocado

Un PDF es un formato de distribución, no de colaboración. Es la elección equivocada cuando:

• El documento cambia a diario y los lectores necesitan la versión más reciente. Enlaza al repositorio o genera el PDF de forma programada.
• El contenido depende de elementos interactivos, datos en vivo o vídeo incrustado. Un PDF aplana todo eso.
• El repositorio es privado y quien lo recibe necesita explorar el código. Un PDF le da una instantánea, no acceso.
• El documento es una sola página corta que se lee perfectamente en el repositorio. Puede que el paso extra no compense.
• Necesitas comentarios y sugerencias con seguimiento. Usa una herramienta de documentos colaborativos; las anotaciones de PDF no sustituyen a los flujos de revisión.

La herramienta no es una plataforma de documentación, y es intencionado. Convierte un documento que ya tienes en uno portátil. Saber cuándo no usarla forma parte de usarla bien.

Lista de comprobación previa de cinco minutos

Comprobación	Por qué importa
El origen es el repositorio o el archivo correcto	Un PDF con el nombre de proyecto equivocado es peor que no tener PDF
La jerarquía de encabezados es coherente	Controla la tabla de contenidos y la estructura de páginas
Las imágenes se resuelven	Las rutas relativas al repositorio necesitan obtener el repositorio
Las líneas de código no son demasiado anchas	Los bloques de código anchos son el problema de recorte más habitual
Las tablas caben en la página	Las tablas de ocho columnas rara vez sobreviven en A4
Los enlaces tienen sentido	Los enlaces blob y los externos deben seguir siendo comprensibles sin conexión
El texto confidencial está eliminado	El PDF se puede reenviar aunque la conversión sea local
El tema encaja con el público	Clean para ingeniería, Business para clientes, Academic para prosa
El tamaño de página coincide con el destinatario	A4 y Carta cambian la paginación
El nombre del archivo incluye una versión	Hace que el artefacto sea trazable

Guía rápida de temas

• Clean — especificaciones, READMEs técnicos, folletos con mucho código, auditorías.
• Business — entregas a clientes, propuestas, materiales de taller, anexos de portafolio.
• Academic — dosieres de curso, artículos, prosa extensa, candidaturas de investigación.
• Dark — revisión en pantalla antes de exportar; la hoja de estilos de impresión lo aclara para papel.

Si tienes dudas, empieza con Clean, exporta una copia y léela en un teléfono o en una página impresa. El tema que se veía mejor en un monitor grande no siempre es el que se lee mejor a la distancia del brazo.

Para el flujo completo, incluidos los ajustes de impresión y la resolución de problemas, consulta Cómo convertir un README de GitHub a PDF. Para un análisis más detallado de los cuatro temas, consulta Clean vs Business vs Academic vs Dark.