Espejo de documentación oficial en markdown, con un visor web estático que funciona sin conexión.
Existe para poder seguir trabajando cuando no hay internet: viajes, averías de red, caídas de servidor, o bloqueos DNS de operadoras que tumban dominios legítimos (en España ha pasado con rangos de Cloudflare por motivos de retransmisiones deportivas).
No pretende ser una solución alarmista, pero me ha sacado de más de un apuro y la comparto por si a alguien le sirve.
make # ayuda
make update # reconstruye todo (lo que ejecuto cada pocos meses)
make status # qué hay descargado y de qué versiónDespués, abre public/index.html en el navegador. Sin servidor, sin Node, sin internet.
Tres capas y una única dirección de flujo:
make fetch make normalize make build
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ work/ │ ──────► │ src/ │ ──────► │ public/ │
│ clones │ │markdown │ │ HTML │
│tarballs │ │canónico │ │ estático│
└─────────┘ └─────────┘ └─────────┘
desechable ★ lo que importa ★ generado
| Directorio | Qué es | ¿Versionado? |
|---|---|---|
work/ |
Clones y tarballs recién descargados | No, se borra tras cada build |
src/ |
Markdown canónico: la única fuente de verdad | Sí |
bundles/ |
Documentación unificada en un solo archivo Markdown por tecnología (para LLMs o lectura offline) | Sí |
public/ |
Sitio HTML navegable y recursos generados | No, se regenera |
scripts/ |
El pipeline y las plantillas | Sí |
sources.yaml |
Catálogo de fuentes | Sí |
Tener el markdown separado del HTML permite además consultarlo con grep, rg o modelos de IA locales sin pelearse con etiquetas. Además, la carpeta bundles/ contiene toda la documentación unificada en un único archivo plano por tecnología para alimentar LLMs de golpe.
| Tecnología | Origen | Formato de origen |
|---|---|---|
| Bash | ftp.gnu.org (tarball) | Texinfo → DocBook con texi2any |
| Composer | composer/composer |
Markdown nativo |
| Debian | salsa.debian.org (debian-reference) |
DocBook XML, convertido con pandoc |
| Docker | docker/docs |
Markdown nativo |
| Filament | filamentphp/filament |
Markdown nativo |
| Git | git/git |
AsciiDoc, convertido con pandoc |
| JavaScript | mdn/content |
Markdown nativo (MDN Web Docs) |
| Laravel | laravel/docs |
Markdown nativo |
| llama.cpp | ggml-org/llama.cpp |
Markdown nativo |
| MicroPython (Pico) | micropython/micropython |
Sphinx RST, convertido con pandoc |
| Node.js | nodejs/node |
Markdown nativo |
| npm | npm/cli |
Markdown nativo |
| Nuxt | nuxt/nuxt |
Markdown nativo |
| PHP | php/doc-es (+ php/doc-base) |
DocBook XML, convertido con pandoc |
| pnpm | pnpm/pnpm.io |
Markdown nativo |
| PostgreSQL | postgres/postgres |
DocBook XML / SGML, convertido con pandoc |
| Python | docs.python.org | Texto plano, sin conversión |
| SQLite | sqlite.org (tarball zip) |
HTML estático limpio, con pandoc |
| Tailwind CSS | tailwindlabs/tailwindcss.com |
MDX (con tablas extraídas a Markdown) |
| Vue 3 | vuejs/docs |
Markdown nativo |
PHP y PostgreSQL se toman de sus fuentes en DocBook/SGML, no de tarballs HTML. Salen más limpios, vienen de git como el resto, y cada fichero conserva su estructura canónica. Para la versión inglesa de PHP basta cambiar el repo a php/doc-en en sources.yaml.
No hace falta escribir un script. Se añade una entrada en sources.yaml:
livewire:
name: Livewire
adapter: git_markdown
repo: https://github.com/livewire/livewire.git
ref: "3.x"
sparse: ["/docs"]
license: MIT
homepage: https://livewire.laravel.com/docsY se ejecuta:
make fetch-one S=livewire
make normalize
make buildAntes de añadir nada, comprueba en qué formato publica su documentación el proyecto. Si usa Sphinx (.rst), no conviertas el .rst directamente: descarga su bundle HTML compilado. Los detalles están en AGENTS.md.
# Debian / Ubuntu
sudo apt install git python3 pandoc
# macOS
brew install git python3 pandoc
# Dependencias de Python
pip3 install pyyaml markdown jinja2 pygments --break-system-packagesmake deps comprueba que está todo.
En reorganización. La arquitectura descrita arriba es la de destino; el plan completo y el análisis de lo que había antes están en ANALISIS-Y-PLAN.md.
- Fase 1 — Base:
AGENTS.md,.gitignore,sources.yaml,Makefile, estructura - Fase 2 — Pipeline para las fuentes con markdown nativo (
fetch,normalize,check) - Fase 3 — Generador de sitio y buscador offline (
build,search) - Fase 4a — PHP desde el fuente DocBook (
docbook,normalize_docbook) - Fase 4b — Python (compilado limpio) y Bash (Texinfo con texi2any)
- Fase 5 — Acabado: bundles unificados para IA (
make bundles), feed RSS 2.0, Sitemap.xml, PWA vanilla y SEO/accesibilidad
Verificado con 16.577 documentos normalizados, validados y publicados en 20 tecnologías:
| Tecnología | Documentos | Formato de origen |
|---|---|---|
| Bash | 70 | Texinfo oficial de GNU |
| Composer | 33 | Markdown nativo |
| Debian Reference | 14 | DocBook XML (debian-reference) |
| Docker | 905 | Markdown nativo (docker/docs) |
| Filament | 82 | Markdown nativo |
| Git | 226 | AsciiDoc oficial (git/git) |
| JavaScript | 1.331 | MDN Web Docs |
| Laravel | 101 | Markdown nativo |
| llama.cpp | 51 | Markdown nativo |
| MicroPython (Pico) | 143 | Sphinx RST (micropython/micropython) |
| Node.js | 70 | Markdown nativo |
| npm | 87 | Markdown nativo |
| Nuxt | 261 | Markdown nativo |
| PHP | 11.000 | DocBook XML (doc-es) |
| pnpm | 140 | Markdown nativo |
| PostgreSQL | 384 | DocBook XML / SGML (postgres/postgres) |
| Python | 536 | Documentación oficial compilada |
| SQLite | 837 | HTML estático procesado con pandoc |
| Tailwind CSS | 197 | MDX procesado a Markdown nativo |
| Vue 3 | 109 | Markdown nativo |
El sitio generado se abre con doble clic en public/index.html: sin servidor, sin conexión y sin cargar ningún recurso externo. Además, bundles/ ofrece 1 archivo Markdown plano por tecnología listo para descargar o usar con IA.
- Portada con una tarjeta por tecnología, indicando versión y fecha de descarga.
- Menú lateral por secciones, plegable, con la página actual resaltada.
- Buscador con atajo
/, navegable con flechas. Índice por tecnología cargado bajo demanda, más un índice global en la portada. - Modo claro y oscuro, siguiendo el sistema o forzado con el conmutador.
- Código resaltado en tiempo de compilación con Pygments: cero JavaScript para colorear.
- Índice de contenidos por página y navegación anterior/siguiente.
Detalle técnico que conviene no tocar: sobre file:// el navegador bloquea fetch(), así que el índice de búsqueda es un .js que declara una variable global, no un .json. Convertirlo a JSON rompería el buscador al abrir el sitio sin servidor.
Las ilustraciones de pnpm (/img/*.svg) no se descargan, porque están fuera de su carpeta de documentación. Son 15 imágenes que se verán rotas; el texto está completo. Se resuelve en una iteración posterior ampliando su sparse en sources.yaml.
Git necesita cambiar permisos, y sobre sistemas de ficheros sincronizados (Google Drive, Dropbox) esas operaciones pueden fallar. Si make fetch da errores de permisos, saca work/ a un disco normal:
make update WORK_DIR=/tmp/docs-worksrc/ y public/ no tienen ese problema: son ficheros normales.
La carpeta repos/ de la versión anterior contenía clones completos (más de 60.000 ficheros de vendor/ y node_modules). Ya no se usa: la sustituye work/ con clones sparse. Para eliminarla:
make clean-allCada documentación mantiene la licencia de su proyecto original, y casi todas exigen conservar la atribución. Ver LICENSES.md.
Este repositorio es un espejo no oficial. La documentación de referencia siempre es la del sitio oficial de cada proyecto; aquí solo se cambia el formato, nunca el contenido.
El código del proyecto (scripts, plantillas y estilos) es de @raupulus.
Las documentaciones incluidas son las que uso a diario. Si echas en falta alguna, adelante: una entrada en sources.yaml y listo.
Requisito estricto: todo lo que se guarde aquí tiene que ser público. Nada de credenciales, tokens, rutas de máquinas privadas ni datos personales, porque la carpeta se comparte.
Mantenido por @raupulus · public@raupulus.dev