Antylogic
DemoApp login

399 operational guides

Docs sections
DocsDocumentation
Device

Sync articles and assets

Prepares the local bundle consumed by Docs: it generates articles.json and manifest.json from a supported source and, if an assets output is configured, packages the media so the backend can later serve it on public and authenticated routes.

In this article

Use this guide when Operations or Documentation need to regenerate the local Docs content before starting or deploying the backend. The action runs from the CLI, not from an Antylogic screen.

The sync keeps the internal content of each article, but it does set bundle metadata such as version, generated_at, locales, platforms and asset_roots. For captures or tests, use temporary outputs under /tmp and avoid touching backend/docs-content unless that is the intent of the release.

Before you start

  • Node.js available in an environment that can run backend/scripts/sync-docs-content.mjs.
  • A supported source: DOCS_GENERATED_SOURCE, a DOCS_SOURCE_DIR with articles.json or wiki-generated-data.ts, or the fallback frontend/landingpage/src/content/wiki-generated-data.ts.
  • Write permission on DOCS_CONTENT_OUTPUT or, if it is not defined, on backend/docs-content.
  • If DOCS_ASSETS_OUTPUT is defined, confirm that it points to a temporary or isolated directory, because it is removed recursively before assets are copied.
  • If authenticated routes are validated after deployment, use the Harbor Demo User session of the GB runtime; the bundle does not depend on Harbor Demo Group or Harbor Soho.

Instructions

  1. 1.

    Choose the documentation source

    Define DOCS_GENERATED_SOURCE if you want to force a specific file. If it is not defined, the script looks for candidates inside DOCS_SOURCE_DIR. Without DOCS_SOURCE_DIR, it uses the local fallback frontend/landingpage/src/content/wiki-generated-data.ts.

  2. 2.

    Prepare outputs and traceability

    Define DOCS_CONTENT_OUTPUT to write the bundle outside backend/docs-content. Define DOCS_ASSETS_OUTPUT only if you want to package media. For an identifiable release, add DOCS_CONTENT_VERSION, DOCS_SOURCE_PROJECT and DOCS_SOURCE_REF.

  3. 3.

    Run the sync

    Launch node backend/scripts/sync-docs-content.mjs from the root, node scripts/sync-docs-content.mjs from backend, or use backend/scripts/prepare-docs-content.sh when the pipeline prepares a remote documentation checkout.

  4. 4.

    Review articles.json

    Check that the generated file contains version, generated_at, source, source_project, source_ref, locales, platforms and articles. The languages must come from article.locale and platforms must stay fixed at mobile, tablet and web.

  5. 5.

    Review manifest.json and assets

    Confirm that articles_file points to articles.json and that asset_roots declares default_local, source, bundled_local and runtime_env. If DOCS_ASSETS_OUTPUT was not defined, do not expect an assets copy even if a local source exists.

  6. 6.

    Validate the Docs runtime

    Start or deploy the backend with DOCS_CONTENT_PATH and DOCS_ASSETS_PATH where applicable. Then validate /api/public/docs without a session and /api/app/docs with a session, plus the assets under /api/public/docs/assets/{path} or /api/app/docs/assets/{path}.

Validations and limits

  • If no candidate source appears, the script fails with Docs source not found and prints the list it checked.
  • The JSON source must be an array or an object with an articles array; the TypeScript source must contain the exact generatedWikiGuideData markers.
  • resetDirectory rejects trivial outputs, but DOCS_ASSETS_OUTPUT remains destructive for any valid directory chosen by mistake.
  • If the script aborts, do not publish a partial articles.json or an old manifest.
  • The analysed bundle contains 708 articles, 354 in en and 354 in es; if the release expects a different count, record the difference before publishing.
  • If the API returns 503 documentacion no configurada or 500 documentacion no disponible, review DOCS_CONTENT_PATH and the decoding of articles.json before investigating the Docs screen.

Expected result

When finished, Docs has a versioned local bundle with articles.json and manifest.json, and optionally an assets output ready for the backend to serve index, detail and media from public and authenticated routes.

Related articles