Documentation Deployment¶
This guide explains how to set up and deploy the Freeze Design documentation to Cloudflare Pages.
Overview¶
The documentation is automatically built and deployed via GitHub Actions:
| Component | URL Path | Source |
|---|---|---|
| Developer Docs | / |
mkdocs-material |
| API Reference | /api/ |
Swagger UI (OpenAPI) |
| Component Library | /storybook/ |
Storybook |
| TypeScript Docs | /typescript/ |
TypeDoc |
Production URL: freezedesign-docs.pages.dev
Cloudflare Pages Setup¶
Step 1: Create Cloudflare Account¶
- Sign up at cloudflare.com
- Navigate to Workers & Pages in the dashboard
Step 2: Create Pages Project¶
- Go to Workers & Pages → Create → Pages
- Select Direct Upload (we deploy via GitHub Actions)
- Name the project:
freezedesign-docs - Click Create project
Step 3: Get API Credentials¶
Account ID:
- Go to any domain or the main dashboard
- Find Account ID in the right sidebar
- Copy this value
API Token:
- Go to My Profile → API Tokens
- Click Create Token
- Use the Edit Cloudflare Workers template
- Or create custom token with permissions:
- Account: Cloudflare Pages - Edit
- Zone: (none needed for Pages)
- Copy the generated token
Step 4: Add GitHub Secrets¶
In your GitHub repository:
- Go to Settings → Secrets and variables → Actions
- Add these secrets:
| Secret Name | Value |
|---|---|
CLOUDFLARE_ACCOUNT_ID |
Your account ID |
CLOUDFLARE_API_TOKEN |
Your API token |
Step 5: Trigger Deployment¶
The docs site deploys from main. Documentation changes follow the normal flow: PR against staging, then staging→main promotion via scripts/release.sh --promote-only after the retest on staging. The workflow has a path filter and only runs when docs/**, backend/**, frontend/**, or the workflow file itself changes.
develop trigger is dead
docs.yml lists both main and develop in its push trigger, but this repository only has main and staging — there is no develop branch, so that half of the trigger never fires. Effectively the deploy is main-only; the deploy job additionally checks github.ref == 'refs/heads/main'. The develop reference is a leftover.
Workflow Details¶
The deployment workflow (.github/workflows/docs.yml) runs:
- Build jobs (parallel):
build-mkdocs- Developer documentation (Python 3.12,pip install -r docs/requirements.txt,mkdocs build --config-file docs/mkdocs.yml --site-dir ../site)build-openapi- API reference from Django (python manage.py spectacular --format openapi-json --file schema.json, wrapped in Swagger UI)build-storybook- React component library (Node 20,npm run build-storybook)-
build-typedoc- TypeScript API documentation (Node 20,npm run docs:typedoc) -
Combine - Merges all outputs into a single site (
combined-docsartifact, kept 1 day) -
Deploy -
cloudflare/wrangler-actionwithpages deploy site --project-name=freezedesign-docs; only onmainpushes. On pull requests thedeploy-previewjob deploys with--branch=<head branch>instead and comments the preview URL. It is skipped for Dependabot PRs (github.actor != 'dependabot[bot]', #875): those runs get no repository secrets, soCLOUDFLARE_API_TOKENwould be missing and the job always failed.
Node 20 in docs.yml
docs.yml still uses Node 20 while ci.yml uses Node 22 and the production image Node 26.
Preview Deployments¶
Pull requests targeting main (i.e. staging→main promotion PRs or release/* PRs that touch docs sources) automatically get preview deployments:
- URL format:
https://<branch-name>.freezedesign-docs.pages.dev - A comment is added to the PR with the preview URL (the
deploy-previewjob has an explicitpull-requests: writepermission for this)
Feature PRs target staging and therefore do not get a docs preview, and Dependabot PRs never get one (no secrets in those runs).
Local Development¶
Build Documentation Locally¶
# MkDocs (developer docs; mkdocs, mkdocs-material, pymdown-extensions,
# mkdocs-git-revision-date-localized-plugin)
cd docs
pip install -r requirements.txt
mkdocs serve -a localhost:8001 # port 8000 is the Django backend
# Storybook
cd frontend
npm install
npm run storybook # http://localhost:6006
# TypeDoc
cd frontend
npm run docs:typedoc
# Output in frontend/typedoc-out/ (typedoc.json)
Mermaid diagrams work in these pages: pymdownx.superfences is configured with a mermaid fence in docs/mkdocs.yml.
Build All Documentation¶
# MkDocs (same command as docs.yml; output in ./site)
mkdocs build --config-file docs/mkdocs.yml --site-dir ../site
# Storybook (output in frontend/storybook-static/)
cd frontend && npm run build-storybook
# TypeDoc
cd frontend && npm run docs:typedoc
Custom Domain (Optional)¶
To use a custom domain like docs.freezedesign.nl:
- Go to Cloudflare Pages → your project → Custom domains
- Click Set up a custom domain
- Enter your domain (e.g.,
docs.freezedesign.nl) - Add the DNS record as instructed
- Wait for SSL certificate provisioning
Troubleshooting¶
Build Failures¶
Check the GitHub Actions logs:
Missing Secrets¶
If deployment fails with authentication errors:
- Verify secrets are set in GitHub
- Check API token has correct permissions
- Ensure account ID is correct
Storybook Build Issues¶
If Storybook fails to build:
Architecture¶
flowchart TD
subgraph Repo["GitHub repository (private)"]
D[docs/ → mkdocs source]
F[frontend/ → Storybook & TypeDoc source]
B[backend/ → OpenAPI schema source]
end
Repo --> GA["GitHub Actions (docs.yml)<br/>builds mkdocs + openapi + storybook + typedoc,<br/>combines into one site"]
GA -->|push to main| CF["Cloudflare Pages<br/>(serves static files)"]
CF --> URL[https://freezedesign-docs.pages.dev]