Publishing model

This document describes how workflow documentation moves from authoritative workflow repositories into the published Docusaurus site. The model is intentionally simple so it can be automated in GitLab CI without redesign.

Lifecycle overview

1. Author     Workflow maintainer edits docs in workflow repo (e.g. superbuild-workflow/docs/)
2. Review     Normal Git review / merge in workflow repo
3. Sync       Portal imports updated Markdown into docs-<workflow>/
4. Integrate  Portal maintainer updates sidebars / config if structure changed
5. Build      npm run build produces static site in build/
6. Publish    Static assets deployed to hosting (GitLab Pages or equivalent)

Steps 3–6 happen in ai-workflows/docs-portal. Steps 1–2 stay in each workflow repository.

Sync

Cross-platform Python tooling — see Sync architecture and Automation model.

pip install -r requirements-sync.txt
python scripts/sync_workflow.py superbuild --source ../superbuild-workflow
python scripts/validate_workflow_import.py superbuild --source ../superbuild-workflow

The sync engine reads workflows/registry.yaml and each workflow's docs/workflow-manifest.yaml, copies mirrored Markdown, optional static companion assets (e.g. templates/ → static/<workflow>-assets/), rewrites portal-specific links, updates sidebars, and in CI may commit with chore(sync): ….

When to sync

Trigger	Action
Workflow repo doc merge to develop	Downstream portal pipeline (automatic)
New workflow doc file added upstream	Sync updates mirror; sidebar from manifest
Portal-only change (common docs, nav)	No sync required
New workflow repo onboarded	Workflow onboarding

Build

Local development:

npm install
npm start          # dev server with hot reload
npm run build      # production static output → build/
npm run serve      # preview production build locally

Production builds should use a clean install (npm ci) and npm run build. The build/ directory is the deployable artifact.

Publish

GitLab CI (.gitlab-ci.yml) builds and publishes via GitLab Pages:

Branch	URL	Role
develop	https://docs-portal-1c6c85.gitlab.io	Automatic publish on every green pipeline
master	https://esys-ai.org	Production (custom domain in GitLab UI)

Jobs: audit:website + typecheck → docs:build → pages (+ docs:smoke on master).

Full runbook: GitLab Pages.

Intended deployment pattern (with workflow sync)

When workflow sync is wired into CI:

1. CI job checks out docs-portal
2. CI clones or fetches pinned workflow repo revisions
3. CI runs sync script(s) for each registered workflow
4. CI runs npm ci && npm run build (docs:build)
5. CI copies build/ to public/ (pages job)

Publishing can be full site rebuild on any upstream change — static sites make this cheap. Partial rebuilds are optional optimizations, not requirements.

Version pinning

For reproducible publishes, pin each workflow source to a known Git ref in CI:

SUPERBUILD_DOCS_REF=develop   # or tag / SHA

Document pin changes in portal commit messages when a publish intentionally snapshots a new upstream state. Consumers reading the live site see whatever ref the portal last synced; the workflow repo's default branch remains the authoring target.

Rollback

Because publish output is a static build from a known portal commit:

• Revert or fix forward in docs-portal and redeploy
• Re-sync from an earlier upstream tag if mirrored content was wrong

Workflow repositories roll back independently via their own Git history; the portal re-syncs when operators choose.

Checklist before first production publish

• Sync all registered workflows from current default branches
• Sidebars list every synced page intended for navigation
• onBrokenLinks: 'throw' passes in npm run build
• Edit URLs in docusaurus.config.ts point at correct GitLab paths
• DOCS_PREVIEW_SITE_URL in .gitlab-ci.yml matches GitLab Deploy → Pages preview URL
• Custom domain esys-ai.org configured on production Pages (master only)
• Pages access set to Everyone (public)
• develop fast-forward merged to master with green CI (production deploy)
• docs:smoke green on master after first pages deploy