🌐 Sitio web — cómo se genera y se publica#
Versión: v1 Estado: 🟢 Activo Uso recomendado: Leer antes de tocar la portada, la documentación publicada o el workflow pages
La web del proyecto vive en https://vladimiracunadev-create.github.io/wsl-labs/ y se genera desde este mismo repositorio. No hay HTML versionado: site/ es salida, se borra y se reconstruye en cada ejecución.
🗺️ Esquema#
flowchart LR
subgraph FUENTES["📥 Fuentes en el repo"]
CAT["containers.config.json"]
VER["version.txt"]
MD["*.md (raíz, docs, cheatsheets, casos)"]
SRC["site-src/ (cuerpo + estilos)"]
end
GEN["scripts/build-site.mjs"]
CHK["scripts/check-site-links.mjs"]
OUT["site/ (HTML generado)"]
PAGES["GitHub Pages"]
CAT --> GEN
VER --> GEN
MD --> GEN
SRC --> GEN
GEN --> OUT
OUT --> CHK
CHK --> PAGES
🧱 Qué se publica#
| Origen en el repo | Página publicada |
|---|---|
site-src/index.html + catálogo | /index.html (portada) |
*.md de la raíz | /readme.html, /changelog.html, /roadmap.html, … |
docs/*.md | /docs/<nombre>.html |
cheatsheets/*.md | /cheatsheets/<nombre>.html |
containers/NN-caso/README.md | /containers/NN-caso/index.html |
| — (generadas) | /docs/index.html, /cheatsheets/index.html, /containers/index.html, /404.html |
El panel de control (
index.html de la raíz, dashboard.js, dashboard.css) no se publica. Escucha en localhost, ejecuta wslc.exe y no tiene autenticación: en internet sería un mando a distancia sin dueño.🔗 Enlaces: todo termina en HTML#
El generador reescribe cada enlace del Markdown según a dónde apunte:
Enlace en el .md | Enlace en la web |
|---|---|
docs/INSTALL.md | docs/install.html |
../README.md | readme.html |
containers/01-node-api/ | containers/01-node-api/index.html |
LICENSE, *.json, *.go | https://github.com/…/blob/main/… |
#-una-seccion | se conserva: los anclajes usan las mismas reglas que GitHub |
scripts/check-site-links.mjs comprueba las tres formas de romper un enlace aquí: una página que no existe, un ancla que nadie define y un fichero enlazado en GitHub que ya no está en el repositorio. Falla con código 1 y el sitio no se publica.
🛠️ Trabajar en local#
make site # genera site/
make site-check # genera site/ y revisa los enlacesPara verlo en el navegador basta con servir la carpeta:
node -e "require('http').createServer((q,s)=>require('fs').createReadStream('site'+(q.url==='/'?'/index.html':q.url)).pipe(s)).listen(4173)"site/ está en .gitignore a propósito. Si aparece en un git status, algo lo está versionando y la web podrá contradecir al repositorio.🤖 Publicación (workflow pages)#
| Paso | Qué hace |
|---|---|
push a main | Solo si cambian site-src/, los generadores, un .md, el catálogo o version.txt |
| Generar | node scripts/build-site.mjs |
| Verificar | Portada con los 12 casos, versión de version.txt, una página por documento y cero enlaces rotos |
| Publicar | actions/upload-pages-artifact + actions/deploy-pages |
Las acciones están fijadas a SHA: el workflow escribe en Pages y no debe depender de una etiqueta móvil.
Pages está activado en el repositorio con origen GitHub Actions. El workflow no intenta crearlo (
enablement: true): esa llamada exige permisos de administración que el GITHUB_TOKEN no tiene y tumbaba el job con el sitio ya generado y verificado.