Docs Site Publishing Runbook

Date: 2026-02-08 Status: Active

Current Recommendation

Use GitHub Pages for docs publishing, with a custom domain docs.a3os.app.

Components

• Source: /docs (Markdown)
• Build tool: MkDocs + Material
• Build workflow: .github/workflows/docs-build.yml
• Publish workflow: .github/workflows/docs-publish.yml

One-Time GitHub Setup

1. In repository settings, enable GitHub Pages with source GitHub Actions.
2. Ensure Actions are allowed to create/deploy pages artifacts.

Domain Setup (docs.a3os.app)

1. Add docs/CNAME with docs.a3os.app.
2. In Route53, create DNS record for docs.a3os.app:
3. CNAME to <org-or-user>.github.io (or provider target shown in Pages settings), or
4. ALIAS if preferred by your DNS policy.
5. In Pages settings, set custom domain to docs.a3os.app and enforce HTTPS.

Validation

• mkdocs build --strict succeeds locally and in CI.
• Docs Publish workflow succeeds on main.
• https://docs.a3os.app resolves with a valid TLS cert.

Rollback

• Re-run last known good publish.
• If domain misconfiguration occurs, temporarily use default GitHub Pages URL.