ComandeskHelp Inicio

Salvaguardas De Enlaces, CSS Y Export Estatico

Objetivo

Evitar repetir los problemas anteriores de documentacion publicada sin estilos, enlaces rotos, rutas absolutas incorrectas o despliegues a una ruta que no era la servida en produccion.

Este documento es obligatorio antes de:

  • compilar documentacion estatica;
  • publicar docs/ops;
  • tocar enlaces dentro de la ayuda;
  • modificar CSS de documentacion o del panel;
  • desplegar public/index.html o public/ops-premium-tokens.css.

Rutas Reales

  • Repo OPS local: /Volumes/Disco SSD/Desarrollo/clientes/soluciones-abiertas/ops.
  • Fuente markdown interna: docs/.
  • Fuente compilada de salvaguardas OPS: docs/ops/.
  • Documentacion interna servida por OPS: https://ops.solucionesabiertas.net/help/.
  • Export estatico publico local: /Volumes/Disco SSD/Desarrollo/docs/ops.
  • Produccion OPS correcta: https://ops.solucionesabiertas.net.
  • Dominio incorrecto para verificar OPS: ops.solucionesabiertas.es.
  • App Node en VPS: localhost:3847.
  • HTML/CSS de app en VPS: /var/www/ops/public/.
  • Nginx raiz /: proxy a Node.
  • Nginx /v1/: alias a /var/www/ops-v1/.

Regla De Oro

No dar por publicado un cambio hasta verificar la misma ruta que consume el usuario final.

Para OPS app, verificar https://ops.solucionesabiertas.net/.

Para documentacion interna, verificar https://ops.solucionesabiertas.net/help/.

Para export publico local, verificar /Volumes/Disco SSD/Desarrollo/docs/ops con el script de verificacion.

Compilacion De Documentacion

Para build simple de ayuda interna:


npm run docs:build-static

Para build publico con plantilla Syntax y rutas portables:


npm run docs:publish-public

Ese comando debe:

  1. compilar con DOCS_BASE_PATH=/ops;
  2. postprocesar enlaces internos a rutas relativas;
  3. publicar en /Volumes/Disco SSD/Desarrollo/docs/ops;
  4. ejecutar docs:verify-publish;
  5. terminar con [docs-verify] OK.

Si no termina en OK, no subir la carpeta.

OPS tiene dos portales:

  • docs:publish-public: portal de usuario/comercial para https://guias.solucionesabiertas.es/ops/.
  • docs:publish-public-es: solo version espanola del portal publico.
  • docs:publish-public-en: solo version inglesa del portal publico en /ops/en/.
  • docs:publish-technical: portal tecnico interno en /Volumes/Disco SSD/Desarrollo/docs/ops-technical/.

No publicar el portal tecnico en la URL publica de usuarios. Arquitectura, runbooks, configuraciones sensibles y estado interno pertenecen al portal tecnico.

El comando recomendado para publicar usuarios es docs:publish-public, porque recompila espanol e ingles en un unico export. Si se publica solo docs:publish-public-es, se puede borrar accidentalmente la carpeta inglesa al sincronizar con --delete.

Publicacion Online

El build local no actualiza por si solo la URL publica. Despues de docs:publish-local, sincronizar el export completo:


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

Este destino corresponde a https://guias.solucionesabiertas.es/ops/. No subir archivos sueltos: si se copian solo HTML y no _next/, la documentacion puede quedar sin CSS/JS.

Verificacion publica obligatoria:


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"

Las respuestas deben ser 200 y Last-Modified debe corresponder al ultimo despliegue. Si sigue mostrando una fecha anterior, el problema no es el build local: falta sincronizar o hay cache.

Salvaguardas De Enlaces

  • Preferir enlaces relativos entre documentos.
  • No usar rutas file://.
  • No enlazar a /Volumes/... desde HTML publico.
  • No enlazar a localhost desde documentacion publicada.
  • No usar URLs absolutas internas si el export puede vivir en /ops/ o en raiz.
  • En Markdown, enlazar a .md; el build debe convertir a .html.
  • En HTML publicado, verificar que no quedan enlaces a .md salvo que sean intencionados como descarga/codigo.
  • Para links externos, usar https:// y revisar que sean intencionados.
  • Para links de OPS app, usar el dominio .net, no .es.

Checks recomendados:


npm run docs:verify-publish

rg -n "file://|localhost|/Volumes/|ops\\.solucionesabiertas\\.es" "/Volumes/Disco SSD/Desarrollo/docs/ops"

rg -n "href=\"/[^\"]+" "/Volumes/Disco SSD/Desarrollo/docs/ops"

El ultimo check puede mostrar falsos positivos si hay assets intencionados, pero debe revisarse antes de publicar.

Salvaguardas De CSS

Ayuda interna simple

El build docs:build-static debe generar:

  • public/help/index.html;
  • public/help/assets/docs.css;
  • out/help/index.html;
  • out/help/assets/docs.css.

Cada HTML debe incluir:

  • link rel="stylesheet" relativo;
  • fallback inline suficiente para que la pagina no quede desnuda.

Export Syntax

El build docs:publish-local debe publicar la carpeta completa:

  • index.html;
  • _next/;
  • docs/;
  • assets generados.

No copiar solo los HTML. Si falta _next/, faltara CSS/JS.

Las rutas de CSS/JS deben quedar relativas:

  • home: _next/...;
  • paginas anidadas: ../../_next/... o equivalente relativo.

No deben quedar rutas absolutas del tipo:

  • /ops/_next/...;
  • /_next/...;
  • /help/_next/...;

salvo que se haya decidido expresamente publicar solo en ese subpath.

Salvaguardas De CSS Del Panel OPS

Antes de desplegar estilos del panel:

  1. validar que public/index.html enlaza /ops-premium-tokens.css;
  2. subir public/ops-premium-tokens.css junto con el HTML si se han tocado tokens;
  3. verificar en VPS que existe el token o selector esperado;
  4. verificar por HTTPS desde el VPS.

Comandos:


ssh sa-tools grep -n -- "--button-radius" /var/www/ops/public/ops-premium-tokens.css

ssh sa-tools "curl -fsS https://ops.solucionesabiertas.net/ops-premium-tokens.css | grep -n -- --button-radius"

Si se toca el selector de temas, verificar tambien:


ssh sa-tools "curl -fsS https://ops.solucionesabiertas.net/ | grep -n 'theme-select'"

Salvaguardas De Despliegue HTML/CSS

Para cambios solo de frontend OPS:


npm run verify:frontend

Ese check valida scripts inline, enlace real a /ops-premium-tokens.css, tokens criticos de temas, presencia de i18n/asistente y referencias peligrosas en href/src/action.

Despliegue:


scp public/index.html sa-tools:/var/www/ops/public/index.html

scp public/ops-premium-tokens.css sa-tools:/var/www/ops/public/ops-premium-tokens.css

Verificacion:


ssh sa-tools "curl -fsS https://ops.solucionesabiertas.net/ | grep -n 'lang-select'"

ssh sa-tools "curl -fsS https://ops.solucionesabiertas.net/ | grep -n 'assistant-toggle-btn'"

No usar ops.solucionesabiertas.es para validar OPS: ese host no es la produccion configurada.

Checklist Antes De Cerrar

  • Build ejecutado.
  • Verificacion OK.
  • CSS externo presente.
  • Fallback CSS presente si aplica.
  • Enlaces internos revisados.
  • Sin file://, localhost, /Volumes/ ni dominio .es en export publico.
  • Carpeta completa publicada, incluyendo _next/ cuando aplique.
  • Ruta final verificada por HTTPS.
  • Cambio documentado en docs/project-state-current.md si afecta a operativa.

Si Algo Falla

  1. No publicar parcialmente.
  2. No editar el export a mano salvo emergencia documentada.
  3. Corregir fuente markdown o script de build.
  4. Recompilar desde cero.
  5. Ejecutar verificacion.
  6. Solo entonces subir la carpeta completa.