# .github/workflows/deploy-docusaurus.yml
#
# This workflow deploys the Blockly documentation to Cloudflare Pages.
# Run this manually after a release to publish updated documentation.
#
# Prerequisites (one-off setup):
#   1. Create the Pages project in Cloudflare (Dashboard -> Workers & Pages -> Create
#      -> Pages -> Direct Upload, or `npx wrangler pages project create blockly-docs`).
#   2. Add the following GitHub Actions secrets (Settings -> Secrets and variables -> Actions):
#        - CLOUDFLARE_API_TOKEN   (token with the "Cloudflare Pages: Edit" permission)
#        - CLOUDFLARE_ACCOUNT_ID  (the Cloudflare account ID)

name: Deploy Docusaurus to Cloudflare Pages

on:
  # To run: GitHub -> Actions -> "Deploy Docusaurus to Cloudflare Pages" -> Run workflow
  # Optionally set `ref` to the release branch/tag
  workflow_dispatch:
    inputs:
      ref:
        description: "Branch, tag, or commit SHA to deploy (defaults to main)"
        required: false
        default: "main"
        type: string

permissions:
  contents: read
  deployments: write

concurrency:
  group: "cloudflare-pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: cloudflare-pages
      url: ${{ steps.deployment.outputs.deployment-url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository
        uses: actions/checkout@v4
        with:
          ref: ${{ inputs.ref || 'main' }}
          # Allow Docusaurus to view the full commit history (required for "last edited at <date> by <person>" functionality)
          fetch-depth: 0

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.x
          cache: "npm"
          cache-dependency-path: "package-lock.json" # root level, since we're using npm workspaces

      - name: Install dependencies
        run: npm ci

      - name: Generate reference docs
        working-directory: ./packages/blockly
        run: |
          npx gulp typings
          npm run docs

      - name: Build the Docusaurus site
        working-directory: ./packages/docs
        run: npm run build
        env:
          # Override by setting the PAGES_BASE_URL repo variable (Settings -> Environments -> cloudflare-pages -> Environment variables) if docs are to be served from a subpath
          BASE_URL: ${{ vars.PAGES_BASE_URL || '/' }}

      - name: Deploy to Cloudflare Pages
        id: deployment
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          # `--branch=main` ensures this is published as a "Production" deployment in the Pages project regardless of which `ref` was checked out for the build
          command: pages deploy ./packages/docs/build --project-name=blockly-docs --branch=main
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}