MkDocs Workflow

Purpose

Define the single source of truth for private documentation hosting, MkDocs authoring workflow, and deployment operations.

Requirements

  • Access must be private (explicit allow-list only).
  • Authentication must support personal Google accounts.
  • Docs must be readable on mobile.
  • Production docs deployment must be CI/CD-only.

Decision

  • Hosting: Cloudflare Pages.
  • Access control: Cloudflare Access.
  • Identity provider: Google IdP.
  • Deployment model: CI/CD workflow from repository.

Why this approach: - Lower operational overhead than AWS S3 + CloudFront + custom auth layers. - Fast setup for private docs with explicit user-level access policies.

Source of truth files

  • MkDocs config: mkdocs.yml
  • Docs content: docs/
  • Docs dependency input: docs/requirements.in
  • Docs dependency lock: docs/requirements.txt
  • Deployment workflow: .github/workflows/docs-deploy.yml

Quick commands

# install dependencies
python -m pip install --upgrade pip
python -m pip install -r docs/requirements.txt

# serve locally
mkdocs serve -a 127.0.0.1:8080

# validate before PR
mkdocs build --strict --site-dir site

Security rules (non-negotiable)

  • Production docs deploy only from CI.
  • Do not deploy production docs from a local machine.
  • Do not use dashboard drag-and-drop for production.
  • Keep Access policy explicit allow-list only (no wildcard include rules).

Local authoring loop

  1. Edit docs under docs/.
  2. Install docs dependencies: bash python -m pip install --upgrade pip python -m pip install -r docs/requirements.txt
  3. Run local docs server: bash mkdocs serve -a 127.0.0.1:8080
  4. Validate build: bash mkdocs build --strict --site-dir site

Updating docs dependencies

Use pip-tools when adding or changing MkDocs plugins/packages.

  1. Update docs/requirements.in.
  2. Recompile lock file: bash python -m pip install --upgrade pip python -m pip install pip-tools pip-compile docs/requirements.in --output-file docs/requirements.txt
  3. Re-run strict build: bash mkdocs build --strict --site-dir site

Current base packages in docs/requirements.in: - mkdocs - mkdocs-mermaid2-plugin

Editing and publishing flow

  1. Update content under docs/.
  2. If adding/changing docs packages, update docs/requirements.in and recompile docs/requirements.txt.
  3. Run local strict validation.
  4. Open PR and let CI validate/deploy according to .github/workflows/docs-deploy.yml.
  5. After merge to main, verify production docs access and content at docs.byteraccoon.com.

Cloudflare Access and Pages setup

  1. Create or use a Pages project for docs.
  2. Bind custom domain docs.byteraccoon.com.
  3. Create Access application for docs.byteraccoon.com.
  4. Configure Google IdP in Cloudflare Access.
  5. Enforce policy:
  6. Include only explicit users/groups.
  7. Remove wildcard (*) include rules.
  8. Keep default deny behavior.

CI/CD deployment flow

  • Trigger: push to main touching docs workflow paths, or manual workflow_dispatch.
  • Build: mkdocs build --strict --site-dir site.
  • Deploy: Cloudflare Pages via cloudflare/wrangler-action@v3.
  • AuthZ/AuthN: Cloudflare Access + Google IdP at docs.byteraccoon.com.

Required GitHub environment secrets: - CF_API_TOKEN - CF_ACCOUNT_ID - CF_PAGES_PROJECT

Validation

  1. Confirm CI workflow succeeded for latest docs change on main.
  2. Confirm docs.byteraccoon.com presents Google login.
  3. Confirm allowed users can access docs.
  4. Confirm non-allowed users are denied.

Operations

  • Onboard user: add to Access allow-list and verify login.
  • Offboard user: remove from Access allow-list immediately.
  • Rotate CF_API_TOKEN on schedule and after personnel changes.
  • Keep branch protection on main.

Rollback

  1. Revert docs commit on main.
  2. Let CI publish the reverted docs version.
  3. Apply temporary deny-all Access policy if incident response requires it.

Troubleshooting

  • If mkdocs build --strict fails on Mermaid URL checks in offline/restricted networks, verify with: bash mkdocs build --site-dir site Then rerun strict mode in a network-enabled environment (CI or local network with internet access).

References

  • Cloudflare Access with Google IdP: https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/google/
  • Cloudflare Pages CI direct upload: https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/
  • Cloudflare Access product: https://www.cloudflare.com/zero-trust/products/access/
  • S3 website access constraints: https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteAccessPermissionsReqd.html