Skip to main content

Docs Publishing

Docs are validated in CI, and AWS docs-site publishing is scaffolded as a manual/protected pipeline stage. Publishing remains disabled until the protected AWS docs variables and access posture are approved.

Prepared publishing options:

  • GitHub Pages for simple public or private repository docs.
  • S3 + CloudFront for AWS-hosted documentation.
  • Vercel for a managed frontend deployment path.
  • Internal docs site behind enterprise identity.

Current commands:

make docs-install
make docs-build
make docs-dev
make docs-serve
make docs-check

AWS docs publishing uses the shared scripts:

bash scripts/ci/build-docs-site.sh
bash scripts/ci/deploy-docs-site.sh

The deploy script refuses to run unless DOCS_SITE_DEPLOY_ENABLED=true and DOCS_SITE_BUCKET are set in a protected environment. CI should assume a dedicated docs deploy role, not the app Helm deploy role.

Before approving a docs deploy for a completed feature, confirm that docs-site/docs/feature-notes/ includes or updates the matching Feature Note.

Publishing must not be enabled without deciding:

  • audience and access control,
  • domain and TLS ownership,
  • preview environment behavior,
  • retention policy for historical docs.

Dependency Audit Note​

The current Docusaurus dependency tree has npm audit findings from transitive packages. Do not use forced dependency upgrades as a routine cleanup because they can create framework churn. Track the findings as a follow-up and resolve them with a minimal, tested dependency update before external publication.