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

Push to the main branch or manually trigger the workflow:

# Via GitHub CLI
gh workflow run docs.yml

# Or push to main
git push origin main

Workflow Details

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

  1. Build jobs (parallel):
  2. build-mkdocs - Developer documentation
  3. build-openapi - API reference from Django
  4. build-storybook - React component library

  5. build-typedoc - TypeScript API documentation

  6. Combine - Merges all outputs into single site

  7. Deploy - Pushes to Cloudflare Pages

Preview Deployments

Pull requests automatically get preview deployments:

  • URL format: https://<branch-name>.freezedesign-docs.pages.dev
  • A comment is added to the PR with the preview URL

Local Development

Build Documentation Locally

# MkDocs (developer docs)
cd docs
pip install -r requirements.txt
mkdocs serve  # http://localhost:8000

# Storybook
cd frontend
npm install
npm run storybook  # http://localhost:6006

# TypeDoc
cd frontend
npm run docs:typedoc
# Output in frontend/typedoc-out/

Build All Documentation

# MkDocs
mkdocs build --config-file docs/mkdocs.yml --site-dir site

# Storybook
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

GitHub Repository (private)
        │
        ├── docs/           → mkdocs source
        ├── frontend/       → Storybook & TypeDoc source
        └── backend/        → OpenAPI schema source
                │
                ▼
        GitHub Actions
        (builds all docs)
                │
                ▼
        Cloudflare Pages
        (serves static files)
                │
                ▼
        https://freezedesign-docs.pages.dev