ComandeskHelp Inicio

Build estatico de docs (HTML + CSS)

Guia corta para compilar la documentacion a HTML estatico y asegurar que el CSS se publique correctamente.

Comando de compilacion

Desde la raiz del repo:


npm run docs:build-static

Si quieres compilar con plantilla Tailwind Plus Syntax (Next + Tailwind):


npm run docs:build-syntax

Esto hace 3 pasos en cadena:

  1. Sincroniza docs/ y docs/sa-ops-system/ al template Syntax.
  2. Compila Next + Tailwind sobre esa version personalizada para OPS Manager.
  3. Copia el export final a out/help-syntax/.

Script de sync: scripts/sync-ops-docs-to-syntax.js.

Opcionalmente puedes fijar base path para evitar rutas absolutas rotas:


DOCS_BASE_PATH=/help npm run docs:build-syntax
  • Por defecto, el export final se postprocesa con rutas relativas, por lo que puede publicarse en raiz, /ops/, /help-syntax/ o una carpeta de preview sin recompilar.
  • DOCS_BASE_PATH sigue siendo util si quieres que Next compile pensando en un subdirectorio concreto antes del postproceso.
  • Para publicar en https://guias.solucionesabiertas.es/ops/, usar:

npm run docs:publish-local

Esto compila el export con DOCS_BASE_PATH=/ops, postprocesa las rutas internas a relativo, lo deja directamente en /Volumes/Disco SSD/Desarrollo/docs/ops/ y ejecuta docs:verify-publish.

El resultado debe ser portable:

  • funciona servido en /ops/;
  • funciona si la carpeta se sube como raiz de un hosting estatico;
  • funciona en previews locales servidos desde la carpeta;
  • no depende de rutas absolutas /ops/_next/... para cargar CSS/JS.

Si por algun motivo necesitas conservar rutas absolutas, ejecutar manualmente con DOCS_RELATIVE_PATHS=0, pero no usarlo para el paquete publico.

Esto genera:

  • HTML en public/help/
  • HTML en out/help/ (artefacto para despliegue)
  • CSS compartido en public/help/assets/docs.css y out/help/assets/docs.css

Tailwind y docs estaticas

  • Pipeline docs:build-static: no compila Tailwind; genera HTML + docs.css simple.
  • Pipeline docs:build-syntax: si compila Tailwind (plantilla Syntax con Next export).
  • Usa docs:build-syntax cuando quieras maquetacion completa de la plantilla Tailwind.

Como se aplica el CSS

  • Cada pagina HTML generada incluye CSS de 2 formas:

- link relativo (.../assets/docs.css)

- fallback inline dentro del HTML

  • El enlace al CSS se calcula en relativo para que funcione tanto en raiz como en subcarpetas (/help/sa-ops-system/...).
  • Si no carga estilos externos, el fallback inline mantiene la maquetacion base.

Checklist antes de subir

  1. Ejecutar npm run docs:build-static.
  2. Verificar archivos:

- out/help/index.html

- out/help/sa-ops-system/index.html

- out/help/assets/docs.css

- (opcional local) public/help/index.html

  1. Abrir una pagina raiz y una anidada para confirmar estilos.

Para version Tailwind Syntax (docs:build-syntax):

  1. Ejecutar npm run docs:build-syntax.
  2. Verificar out/help-syntax/index.html y out/help-syntax/_next/static/css/*.css.
  3. Publicar out/help-syntax/ completo (incluyendo _next/).

Portales De Documentacion

OPS mantiene dos portales separados:

  • public: portal para usuarios, evaluadores y parte comercial. Incluye que es OPS, por que usarlo, guias de uso y descripcion de funcionalidades.
  • technical: portal tecnico interno. Incluye arquitectura, configuraciones, runbooks, estado del proyecto, salvaguardas y detalles de mantenimiento.

El portal publico se publica en https://guias.solucionesabiertas.es/ops/ con espanol como version principal e ingles en https://guias.solucionesabiertas.es/ops/en/. El portal tecnico se genera localmente en /Volumes/Disco SSD/Desarrollo/docs/ops-technical/ y no debe subirse al portal publico.

Comandos:


npm run docs:publish-public

npm run docs:publish-public-es

npm run docs:publish-public-en

npm run docs:publish-technical

npm run docs:publish-public compila espanol e ingles en un mismo export publico portable. npm run docs:publish-local es alias de docs:publish-public para mantener compatibilidad con el flujo anterior.

Para version publica OPS:

  1. Ejecutar npm run docs:publish-public.
  2. El comando debe terminar con [docs-verify] OK.
  3. Subir completa la carpeta /Volumes/Disco SSD/Desarrollo/docs/ops/ al subdirectorio publico /ops/. No subir solo una version de idioma.

Destino online verificado:


rsync -az --delete "/Volumes/Disco SSD/Desarrollo/docs/ops/" host-webs:/var/www/vhosts/solucionesabiertas.es/guias.solucionesabiertas.es/ops/

No usar este paso si docs:verify-publish falla. El comando sincroniza el subdirectorio publico https://guias.solucionesabiertas.es/ops/, no el DocumentRoot completo.

Verificacion minima despues de subir:


curl -I -L "https://guias.solucionesabiertas.es/ops/docs/how-to-home/"

curl -I -L "https://guias.solucionesabiertas.es/ops/docs/project-state-current/"

curl -I -L "https://guias.solucionesabiertas.es/ops/_next/static/css/48c45ab1e4805ac4.css"

Los tres deben devolver 200; las paginas deben ser text/html y el CSS debe ser text/css. Revisar Last-Modified para confirmar que no se esta viendo una version antigua.

Troubleshooting rapido

  • Pagina sin estilos:

- Confirmar que el servidor esta sirviendo out/help/assets/docs.css (o public/help/assets/docs.css en local).

- Confirmar que el HTML contiene link rel="stylesheet".

- En Syntax, confirmar que el href del CSS es relativo (_next/... en la home o ../../_next/... en paginas anidadas).

- Ejecutar npm run docs:verify-publish; si falla, no subir.

- Si hay CDN/cache, invalidar cache de public/help/*.

- Confirmar que no se esta abriendo un HTML viejo generado antes del fallback inline.

  • Estilos viejos:

- Recompilar y volver a subir public/help/ completo.

Fuente tecnica

  • Script: scripts/build-docs-static.js
  • Syntax publish: scripts/build-docs-syntax-template.sh
  • Verificacion portable: scripts/verify-docs-static.js
  • Entry npm: package.json -> docs:build-static