Antylogic
Probar demoAcceso app

399 guías operativas

Secciones de Docs
DocsDocumentación y ayuda
Dispositivo

Sincronizar articles y assets

Prepara el bundle local que consume Docs: genera articles.json y manifest.json desde una fuente soportada y, si se configura una salida de assets, empaqueta la media para que el backend la sirva después en rutas públicas y autenticadas.

En este artículo

Usa esta guía cuando Operaciones o Documentación necesiten regenerar el contenido local de Docs antes de arrancar o desplegar el backend. La acción se ejecuta por CLI, no desde una pantalla de Antylogic.

El sync conserva el contenido interno de cada artículo, pero sí fija metadatos del bundle como version, generated_at, locales, platforms y asset_roots. Para capturas o pruebas, usa salidas temporales bajo /tmp y evita tocar backend/docs-content salvo que esa sea la intención del release.

Antes de empezar

  • Node.js disponible en un entorno que pueda ejecutar backend/scripts/sync-docs-content.mjs.
  • Una fuente soportada: DOCS_GENERATED_SOURCE, un DOCS_SOURCE_DIR con articles.json o wiki-generated-data.ts, o el fallback frontend/landingpage/src/content/wiki-generated-data.ts.
  • Permiso de escritura sobre DOCS_CONTENT_OUTPUT o, si no se define, sobre backend/docs-content.
  • Si se define DOCS_ASSETS_OUTPUT, confirmar que apunta a un directorio temporal o aislado, porque se elimina recursivamente antes de copiar assets.
  • Si se validan rutas autenticadas después del despliegue, usar la sesión Demo Marea del runtime ES; el bundle no depende de Grupo Marea Demo ni de Marea Gran Via.

Instrucciones

  1. 1.

    Elegir la fuente de documentación

    Define DOCS_GENERATED_SOURCE si quieres forzar un archivo concreto. Si no se define, el script busca candidatos dentro de DOCS_SOURCE_DIR. Sin DOCS_SOURCE_DIR, usa el fallback local frontend/landingpage/src/content/wiki-generated-data.ts.

  2. 2.

    Preparar salidas y trazabilidad

    Define DOCS_CONTENT_OUTPUT para escribir el bundle fuera de backend/docs-content. Define DOCS_ASSETS_OUTPUT solo si quieres empaquetar media. Para un release identificable, añade DOCS_CONTENT_VERSION, DOCS_SOURCE_PROJECT y DOCS_SOURCE_REF.

  3. 3.

    Ejecutar el sync

    Lanza node backend/scripts/sync-docs-content.mjs desde la raíz, node scripts/sync-docs-content.mjs desde backend, o usa backend/scripts/prepare-docs-content.sh cuando el pipeline prepare un checkout remoto de documentación.

  4. 4.

    Revisar articles.json

    Comprueba que el archivo generado contiene version, generated_at, source, source_project, source_ref, locales, platforms y articles. Los idiomas deben salir de article.locale y platforms debe quedar fijo en mobile, tablet y web.

  5. 5.

    Revisar manifest.json y assets

    Confirma que articles_file apunta a articles.json y que asset_roots declara default_local, source, bundled_local y runtime_env. Si DOCS_ASSETS_OUTPUT no se definió, no esperes copia de assets aunque exista una fuente local.

  6. 6.

    Validar el runtime de Docs

    Arranca o despliega el backend con DOCS_CONTENT_PATH y DOCS_ASSETS_PATH cuando aplique. Después valida /api/public/docs sin sesión y /api/app/docs con sesión, además de los assets bajo /api/public/docs/assets/{path} o /api/app/docs/assets/{path}.

Validaciones y límites

  • Si no aparece una fuente candidata, el script falla con Docs source not found e imprime la lista revisada.
  • La fuente JSON debe ser un array o un objeto con articles array; la fuente TypeScript debe contener los marcadores exactos de generatedWikiGuideData.
  • resetDirectory rechaza salidas triviales, pero DOCS_ASSETS_OUTPUT sigue siendo destructivo para cualquier directorio válido elegido por error.
  • Si el script aborta, no publiques un articles.json parcial ni un manifest antiguo.
  • El bundle analizado contiene 708 artículos, 354 en en y 354 en es; si el release espera otro recuento, registra la diferencia antes de publicar.
  • Si la API devuelve 503 documentacion no configurada o 500 documentacion no disponible, revisa DOCS_CONTENT_PATH y la decodificación de articles.json antes de investigar la pantalla Docs.

Resultado esperado

Al terminar, Docs dispone de un bundle local versionado con articles.json y manifest.json, y opcionalmente una salida de assets lista para que el backend sirva índice, detalle y media desde rutas públicas y autenticadas.

Artículos relacionados