Skip to content

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

  1. Sign up at cloudflare.com
  2. Navigate to Workers & Pages in the dashboard

Step 2: Create Pages Project

  1. Go to Workers & Pages → Create → Pages
  2. Select Direct Upload (we deploy via GitHub Actions)
  3. Name the project: freezedesign-docs
  4. Click Create project

Step 3: Get API Credentials

Account ID:

  1. Go to any domain or the main dashboard
  2. Find Account ID in the right sidebar
  3. Copy this value

API Token:

  1. Go to My Profile → API Tokens
  2. Click Create Token
  3. Use the Edit Cloudflare Workers template
  4. Or create custom token with permissions:
  5. Account: Cloudflare Pages - Edit
  6. Zone: (none needed for Pages)
  7. Copy the generated token

Step 4: Add GitHub Secrets

In your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. 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.

# Manual trigger via GitHub CLI
gh workflow run docs.yml

Workflow Details

The deployment workflow (.github/workflows/docs.yml) runs:

  1. Build jobs (parallel):
  2. build-mkdocs - Developer documentation (Python 3.12, pip install -r docs/requirements.txt, mkdocs build --config-file docs/mkdocs.yml --site-dir ../site)
  3. build-openapi - API reference from Django (python manage.py spectacular --format openapi-json --file schema.json, wrapped in Swagger UI)
  4. build-storybook - React component library (Node 20, npm run build-storybook)
  5. build-typedoc - TypeScript API documentation (Node 20, npm run docs:typedoc)

  6. Combine - Merges all outputs into a single site (combined-docs artifact, kept 1 day)

  7. Deploy - cloudflare/wrangler-action with pages deploy site --project-name=freezedesign-docs; only on main pushes. On pull requests the deploy-preview job 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, so CLOUDFLARE_API_TOKEN would 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-preview job has an explicit pull-requests: write permission 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:

  1. Go to Cloudflare Pages → your project → Custom domains
  2. Click Set up a custom domain
  3. Enter your domain (e.g., docs.freezedesign.nl)
  4. Add the DNS record as instructed
  5. Wait for SSL certificate provisioning

Troubleshooting

Build Failures

Check the GitHub Actions logs:

gh run list --workflow=docs.yml
gh run view <run-id> --log

Missing Secrets

If deployment fails with authentication errors:

  1. Verify secrets are set in GitHub
  2. Check API token has correct permissions
  3. Ensure account ID is correct

Storybook Build Issues

If Storybook fails to build:

cd frontend
rm -rf node_modules
npm ci
npm run build-storybook

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]