Exportar un README de GitHub y su documentación a PDF

Por Fazt · Actualizada el 7 de octubre de 2026

Un README se escribe para quien navega por un repositorio, pero tarde o temprano alguien lo necesita como documento: un cliente que tiene que dar el visto bueno a una entrega, un auditor que pide la documentación de una versión concreta o tú mismo, que quieres una copia sin conexión. GitHub muestra muy bien el Markdown en pantalla, pero no tiene ningún botón para convertir un archivo en PDF. Como un README es solo Markdown, puedes tomar el texto fuente, arreglar lo poco que solo tiene sentido dentro de un repositorio e imprimirlo con una tipografía cuidada. ¿Buscas el camino inverso, de Word a README? Consulta Convertir un documento de Word en un README de GitHub.

1. Consigue el Markdown en bruto

Para un solo archivo, ábrelo en GitHub (haz clic en README.md en la lista de archivos, no en la portada del repositorio) y pulsa Raw en la esquina superior derecha de la vista del archivo. Selecciona todo el texto plano, cópialo y pégalo en el panel de Markdown del editor. El icono de copiar que hay junto a Raw hace lo mismo en un clic.

Para varios archivos, como una carpeta docs/, lleva el repositorio a tu disco. Usa Code → Download ZIP o clona solo la última versión:

git clone --depth 1 https://github.com/acme/widget.git

Después usa Abrir archivo .md. Carga un único archivo y sustituye lo que hubiera en el editor; en el apartado 4 verás cómo unir varios archivos antes.

2. Reescribe las rutas relativas

En GitHub, ![Captura](docs/captura.png) se resuelve dentro del repositorio. La página del editor no está en tu repositorio, así que el navegador busca docs/captura.png en el propio sitio del editor, no la encuentra y muestra una imagen rota. Los enlaces relativos como [Cómo contribuir](CONTRIBUTING.md) fallan por el mismo motivo.

La solución es convertir cada ruta en absoluta:

Imágenes: https://raw.githubusercontent.com/USUARIO/REPO/RAMA/ruta/a/imagen.png
Enlaces a otros archivos: https://github.com/USUARIO/REPO/blob/RAMA/ruta/a/archivo.md, para que quien lea llegue a la página ya renderizada en GitHub.

Un ejemplo: en el repositorio acme/widget, rama main, el archivo docs/setup.md contiene:

![Arquitectura](images/arquitectura.png)
<img src="../assets/logo.svg" width="120">
Consulta la [referencia de configuración](configuration.md#variables-de-entorno).

Las rutas son relativas a la carpeta del archivo, aquí docs/, y ../ sube un nivel. Así que queda:

![Arquitectura](https://raw.githubusercontent.com/acme/widget/main/docs/images/arquitectura.png)
<img src="https://raw.githubusercontent.com/acme/widget/main/assets/logo.svg" width="120">
Consulta la [referencia de configuración](https://github.com/acme/widget/blob/main/docs/configuration.md#variables-de-entorno).

Una ruta que empieza por / es relativa a la raíz del repositorio. Si el PDF documenta una versión concreta, usa su etiqueta en lugar de la rama (…/acme/widget/v2.4.0/docs/…): así las imágenes coincidirán con esa versión aunque main siga avanzando.

No hace falta editar línea por línea. Haz clic en el panel de Markdown y pulsa Ctrl+F (Cmd+F en Mac): el panel de búsqueda incluye un campo para reemplazar y un botón replace all. Busca ](images/ y sustitúyelo por ](https://raw.githubusercontent.com/acme/widget/main/docs/images/; luego haz lo mismo con cada atributo HTML src="…" que todavía no sea una URL completa.

3. Qué se conserva de GitHub

El editor entiende la mayor parte del Markdown de GitHub (puedes compararlo con su referencia de sintaxis), pero algunos extras necesitan un pequeño ajuste:

Función de GitHub	En el PDF	Qué hacer
Tablas, alineación de columnas, tachado, notas al pie	Funcionan	Nada
Listas de tareas (`- [x]`)	Funcionan, como casillas marcadas y vacías	Nada
Bloques de código con lenguaje	Resaltados en más de 20 lenguajes habituales, como Bash, Python, JavaScript, TypeScript, Go, Rust, Java, C#, SQL y YAML	Otros, como PowerShell, GraphQL, HCL o Lua, salen como texto monoespaciado sin color
Diagramas Mermaid	Funcionan, como gráficos vectoriales	Nada
Fórmulas con $…$ y `$$…$$`	Funcionan	Cambia los bloques ```math por `$$…$$`
Enlaces automáticos	Las URLs completas (`https://…`) se convierten en enlaces	Escribe como URL completa las direcciones `www.`, las issues `#123` y las menciones `@usuario`
Avisos (`> [!NOTE]`)	Una cita normal con `[!NOTE]` a la vista	Sustituye el marcador por una etiqueta en negrita
`<details>` y `<summary>`	Funcionan, pero se imprimen plegados	Escribe `<details open>`
HTML (`<p align="center">`, `<img width="…">`, `<br>`)	Funciona; los scripts se eliminan	Haz absolutos los `src` y `href`
Insignias (shields.io)	Se cargan como cualquier otra imagen	Plantéate quitarlas para lectores sin perfil técnico
Códigos de emoji (`:rocket:`)	Se imprimen tal cual	Pega el emoji directamente (🚀)
Anclas de los títulos	Se generan automáticamente	Revisa los enlaces a títulos con tildes, símbolos o emojis

Un aviso se convierte así: > [!WARNING] seguido de > Haz una copia de la base de datos antes de actualizar. pasa a ser > **Atención:** Haz una copia de la base de datos antes de actualizar. En el editor, las citas se muestran en cursiva con una línea a la izquierda.

Los identificadores de los títulos siguen la regla de GitHub en los casos sencillos: ## Getting started da #getting-started y un título repetido recibe -1, -2, así que un índice escrito a mano sigue funcionando. Las tildes son la excepción: ## Instalación rápida da #instalacion-rapida, mientras que GitHub conserva #instalación-rápida. Si tu documentación está en español, revisa esos enlaces en la vista previa.

Además, en el texto normal el editor convierte las comillas rectas en tipográficas y -- en un guion medio (–); el código no se toca, así que los comandos se pueden copiar sin problemas.

4. Une README, documentación y changelog

Para obtener un único manual, junta los archivos en un solo Markdown con un marcador de salto de página entre ellos, de modo que cada uno empiece en una página nueva. Antes, reescribe las rutas relativas de cada archivo: images/flujo.png no significa lo mismo dentro de docs/ que en la raíz. Después, en macOS, Linux o Git Bash:

awk 'FNR==1 && NR>1 {print "\n<!-- pagebreak -->\n"} 1' README.md docs/*.md CHANGELOG.md > handbook.md

En PowerShell:

(Get-Content README.md, docs\*.md, CHANGELOG.md -Raw -Encoding utf8) -join "`n`n<!-- pagebreak -->`n`n" | Set-Content handbook.md -Encoding utf8

El patrón docs/*.md ordena los archivos alfabéticamente; escríbelos uno a uno si necesitas otro orden. Abre handbook.md con Abrir archivo .md y haz dos ajustes más:

Los enlaces entre archivos ahora apuntan dentro del mismo documento: cambia [Configuración](docs/configuration.md) por [Configuración](#configuracion).
El primer título se usa como nombre sugerido del PDF, así que empieza por el título # del proyecto.

Los changelogs crecen mucho. Para un cliente suelen bastar las dos o tres últimas versiones; recorta el resto o enlaza al archivo completo en GitHub.

5. Usa el tema Technical para documentación con mucho código

Abre el panel Estilo. Technical combina Roboto para el texto con JetBrains Mono en los títulos, en verde oscuro, y encaja con la documentación para desarrolladores. No hay un ajuste aparte para la fuente del código: los bloques de código usan JetBrains Mono en todos los temas, al 82 % del tamaño del texto, así que el control Tamaño de letra ajusta ambos. Con los 11 pt por defecto, en A4 y con márgenes normales, una línea de código admite unos 85 caracteres; con 10 pt y márgenes Estrechos te acercas a 100.

Para lectores que no programan, Modern o Clean resultan menos técnicos, y los bloques de código conservan igualmente su fuente monoespaciada.

6. Exporta y entrega el PDF

Haz clic en Descargar PDF y elige Guardar como PDF en el diálogo de impresión; el editor espera a que carguen las imágenes antes de abrirlo. Desactiva Encabezados y pies de página para quitar la fecha y la dirección de la página. Ten en cuenta la contrapartida: el editor no tiene un ajuste para numerar páginas, así que, si el cliente necesita números de página, deja activados los encabezados y pies y acepta la fecha, el título y la dirección que el navegador imprime alrededor. Evita Más → PDF rápido para documentación: guarda las páginas como imágenes, y nadie podrá buscar en el texto ni copiar un comando.

Antes de enviar un README a personas sin perfil técnico:

Quita la fila de insignias y las secciones solo para desarrolladores (compilar desde el código, cómo contribuir, configuración de CI), o muévelas a un anexo tras un salto de página.
Añade bajo el título una línea con la versión y la fecha, por ejemplo Versión 2.4 · 7 de octubre de 2026. Sin encabezados, nada más en la página indica qué versión están leyendo.
Escribe textos de enlace que tengan sentido en papel, o muestra la dirección completa, porque en una hoja impresa no se puede hacer clic.

Solución de problemas

Una imagen aparece rota o solo se ve su texto alternativo. La ruta sigue siendo relativa o el repositorio es privado: las imágenes de un repositorio privado no son públicas, así que no cargan en el editor. Alójala en un sitio público o incrústala: codifícala con base64 -w0 diagrama.png (Linux y Git Bash; base64 -i diagrama.png en macOS) y escribe ![Diagrama](data:image/png;base64,iVBOR…). Funciona con PNG, JPEG, GIF y WebP, pero no con SVG.
Las imágenes se ven en la vista previa pero no en el PDF rápido. El PDF rápido vuelve a dibujar la página en un lienzo (canvas), y el navegador solo lo permite con imágenes cuyo servidor autoriza el uso entre orígenes (CORS). raw.githubusercontent.com e img.shields.io lo autorizan; otros servidores no. Descargar PDF imprime cualquier imagen que muestre la vista previa.
Líneas de código largas. Pasan a la línea siguiente en lugar de cortarse, pero un comando partido es fácil de copiar mal. Divide los comandos largos con \ al final de la línea (un acento grave, `, en PowerShell) o baja el tamaño de letra.
Tablas anchas. Las columnas se estrechan hasta caber en la página, y las filas nunca se parten entre páginas. Baja la letra a 9 o 10 pt, elige márgenes estrechos, abrevia los encabezados o divide la tabla en dos. El panel Estilo no tiene orientación horizontal.
Un diagrama Mermaid aparece como texto rojo. Es el mensaje de error de Mermaid: el código del diagrama tiene un error de sintaxis.

Todo ocurre en tu navegador: el Markdown nunca se sube, algo importante con documentación interna. Para ver todos los elementos que admite el editor, consulta la guía de Markdown.