Deploy a Cloudflare Pages

Guía para deployar este folder de documentación como un site estático en Cloudflare Pages.

Recomendación: Opción A (VitePress) — es TypeScript, se integra naturalmente con el stack del proyecto, y produce un site rápido y buscable.

---

Opción A: VitePress (recomendada)

VitePress es el SSG del ecosistema Vue/Vite. Procesa Markdown con soporte nativo de Mermaid via plugins y produce un site completamente estático.

1. Inicializar VitePress

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

Cuando pregunte el directorio: docs/commissions-site

2. Configurar docs/commissions-site/.vitepress/config.mts

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'Comisiones SipSop',
  description: 'Documentación del módulo de comisiones de SipSop',
  lang: 'es',

  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
  ],

  themeConfig: {
    logo: '/logo.svg',
    siteTitle: 'Comisiones SipSop',

    nav: [
      { text: 'Inicio', link: '/' },
      { text: 'API Reference', link: '/api-reference' },
    ],

    sidebar: [
      {
        text: 'Introducción',
        items: [
          { text: 'Inicio', link: '/index' },
          { text: 'Conceptos', link: '/conceptos' },
          { text: 'Happy path', link: '/happy-path' },
        ],
      },
      {
        text: 'Referencia técnica',
        items: [
          { text: 'Arquitectura', link: '/arquitectura' },
          { text: 'Operaciones', link: '/operaciones' },
          { text: 'Portal vendedor', link: '/portal-vendedor' },
          { text: 'API Reference', link: '/api-reference' },
        ],
      },
      {
        text: 'Soporte',
        items: [
          { text: 'FAQ', link: '/faq' },
          { text: 'Deploy', link: '/deploy' },
        ],
      },
    ],

    socialLinks: [
      { icon: 'github', link: 'https://github.com/sopinf/sipsop' },
    ],

    search: {
      provider: 'local',
    },

    footer: {
      message: 'Sopinf Tech LLC — SipSop MSP',
    },
  },

  // Mermaid support
  markdown: {
    config: (md) => {
      // Si usas vitepress-plugin-mermaid:
      // md.use(Mermaid)
    },
  },
})

3. Soporte de Mermaid

VitePress no incluye Mermaid de serie. Instalá el plugin:

pnpm add -D vitepress-plugin-mermaid mermaid

Actualizar config.mts:

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

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

4. Build local

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

Para preview local:

pnpm vitepress preview docs/commissions-site

5. Deploy a Cloudflare Pages via Wrangler

# Instalar Wrangler si no está
pnpm add -D wrangler

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

---

wrangler.toml de ejemplo

Si preferís tener el proyecto de Pages configurado en el repo:

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

[env.production]
vars = {}

---

GitHub Actions: deploy automático

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

name: Deploy commissions docs

on:
  push:
    branches:
      - main
    paths:
      - 'docs/commissions-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 vitepress build docs/commissions-site

      - 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/commissions-site/.vitepress/dist --project-name=sipsop-commissions-docs --branch=main

Secrets requeridos en el repo de GitHub:

• CLOUDFLARE_API_TOKEN: token con permiso de Pages deployment.
• CLOUDFLARE_ACCOUNT_ID: ID de la cuenta de Cloudflare.

---

Custom domain

Desde el dashboard de Cloudflare Pages:

1. Settings → Custom domains → Add custom domain.
2. Ingresar el dominio (ej: docs.commissions.sipsop.net).
3. Cloudflare genera los registros DNS automáticamente si el dominio también está en Cloudflare.

Si el dominio está en otro registrar, agregar el CNAME que Cloudflare indica.

---

Headers de seguridad

Crear docs/commissions-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';

El archivo _headers en la carpeta de output de Pages se procesa automáticamente por Cloudflare.

---

Opción B: Astro Starlight

Más features out-of-the-box (i18n, versioning, sidebar auto-generado desde rutas) pero más setup inicial.

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

Build output: docs/commissions-site/dist/. Deploy igual que VitePress pero apuntando a esa carpeta.

Starlight tiene soporte de Mermaid via @astrojs/mdx + mermaid.

---

Opción C: MkDocs Material

Opción en Python. Simple de configurar, con búsqueda integrada y soporte de Mermaid nativo.

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

docs/commissions-site/mkdocs.yml:

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

plugins:
  - search
  - mermaid2

nav:
  - Inicio: index.md
  - Conceptos: conceptos.md
  - Happy path: happy-path.md
  - Arquitectura: arquitectura.md
  - Operaciones: operaciones.md
  - Portal vendedor: portal-vendedor.md
  - API Reference: api-reference.md
  - FAQ: faq.md
  - Deploy: deploy.md

Build: mkdocs build --config-file docs/commissions-site/mkdocs.yml

No requiere Node. Pero introduce Python como dependencia en el pipeline de CI.

---

Opción D: Markdown raw en Cloudflare Pages

Cloudflare Pages no renderiza Markdown nativamente. Esta opción requeriría un worker de transformación o usar @cloudflare/kv-asset-handler con un parser de Markdown. No recomendada para documentación — el resultado es HTML sin estilos ni navegación.

---

Checklist pre-deploy

• [ ] Build local sin errores: pnpm vitepress build docs/commissions-site
• [ ] Preview local funciona: pnpm vitepress preview docs/commissions-site
• [ ] Diagramas Mermaid se renderizan correctamente
• [ ] Links relativos entre páginas funcionan (ej: ./architecture.md)
• [ ] Búsqueda funciona en local
• [ ] Headers de seguridad configurados en _headers
• [ ] Secrets de GitHub Actions configurados
• [ ] Custom domain configurado (si aplica)