Deploy to Cloudflare Pages

Guide for deploying this documentation folder as a static site on Cloudflare Pages.

Recommendation: Option A (VitePress) — it's TypeScript, integrates naturally with the project's stack, and produces a fast, searchable site.

---

Option A: VitePress (recommended)

VitePress is the SSG of the Vue/Vite ecosystem. It processes Markdown with native Mermaid support via plugins and produces a fully static site.

1. Initialize VitePress

cd /path/to/SipSop
pnpm add -D vitepress
pnpm vitepress init

When asked for the directory: docs/site

2. Configure docs/site/.vitepress/config.mts

The unified i18n config already lives at docs/site/.vitepress/config.mts. No separate config needed — the unified site covers both product and commissions sections in English and Spanish.

3. Mermaid support

VitePress does not include Mermaid out of the box. Install the plugin:

pnpm add -D vitepress-plugin-mermaid mermaid

Update config.mts:

import { withMermaid } from 'vitepress-plugin-mermaid'

export default withMermaid(defineConfig({
  // ... existing config
}))

4. Local build

pnpm docs:build
# Output: docs/site/.vitepress/dist/

Local preview:

pnpm docs:preview

5. Deploy to Cloudflare Pages via Wrangler

# Install Wrangler if not already installed
pnpm add -D wrangler

# Deploy
pnpm wrangler pages deploy docs/site/.vitepress/dist \
  --project-name sipsop-docs \
  --branch main

---

wrangler.toml example

If you prefer to keep the Pages project configured in the repo:

name = "sipsop-docs"
pages_build_output_dir = "docs/site/.vitepress/dist"

[env.production]
vars = {}

---

GitHub Actions: automatic deploy

Create .github/workflows/docs-deploy.yml:

name: Deploy docs

on:
  push:
    branches:
      - main
    paths:
      - 'docs/site/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy to Cloudflare Pages
    permissions:
      contents: read
      deployments: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 9

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build VitePress
        run: pnpm docs:build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy docs/site/.vitepress/dist --project-name=sipsop-docs --branch=main

Required secrets in the GitHub repo:

• CLOUDFLARE_API_TOKEN: token with Pages deployment permission.
• CLOUDFLARE_ACCOUNT_ID: Cloudflare account ID.

---

Custom domain

From the Cloudflare Pages dashboard:

1. Settings → Custom domains → Add custom domain.
2. Enter the domain (e.g., docs.sipsop.net).
3. Cloudflare generates DNS records automatically if the domain is also on Cloudflare.

If the domain is at another registrar, add the CNAME that Cloudflare provides.

---

Security headers

Create docs/site/.vitepress/public/_headers:

/*
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()
  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self';

The _headers file in the Pages output folder is processed automatically by Cloudflare.

---

Option B: Astro Starlight

More features out of the box (i18n, versioning, auto-generated sidebar from routes) but more initial setup.

pnpm create astro@latest docs/starlight-site --template starlight

Build output: docs/starlight-site/dist/. Deploy the same way as VitePress but pointing to that folder.

Starlight has Mermaid support via @astrojs/mdx + mermaid.

---

Option C: MkDocs Material

A Python option. Simple to configure, with built-in search and native Mermaid support.

pip install mkdocs-material
pip install mkdocs-mermaid2-plugin

mkdocs.yml:

site_name: SipSop Docs
theme:
  name: material
  palette:
    primary: deep-orange    # closest to #e8590c
    accent: deep-orange
  font:
    text: IBM Plex Mono

plugins:
  - search
  - mermaid2

nav:
  - Home: index.md
  - Product:
    - Welcome: product/index.md
    - Getting started: product/getting-started.md
  - Commissions:
    - Overview: commissions/index.md
    - Key concepts: commissions/concepts.md

Build: mkdocs build

No Node required. But introduces Python as a dependency in the CI pipeline.

---

Option D: Raw Markdown on Cloudflare Pages

Cloudflare Pages does not render Markdown natively. This option would require a transformation worker or using @cloudflare/kv-asset-handler with a Markdown parser. Not recommended for documentation — the result is unstyled HTML with no navigation.

---

Pre-deploy checklist

• [ ] Local build with no errors: pnpm docs:build
• [ ] Local preview works: pnpm docs:preview
• [ ] Mermaid diagrams render correctly
• [ ] Relative links between pages work (e.g., ./architecture)
• [ ] Search works locally
• [ ] Security headers configured in _headers
• [ ] GitHub Actions secrets configured
• [ ] Custom domain configured (if applicable)