docs.yml

name: Documentation

on:
  push:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'res/**'
      - 'package.json'
      - 'packages/**/*.ts'
      - 'packages/**/*.tsx'
      - 'typedoc.json'
      - 'scripts/generate-api-docs.cjs'
      - 'scripts/sync-brand-assets.mjs'
      - '.github/workflows/docs.yml'
  pull_request:
    branches: [ main, next ]
    paths:
      - 'docs/**'
      - 'res/**'
      - 'package.json'
      - 'packages/**/*.ts'
      - 'packages/**/*.tsx'
      - 'typedoc.json'
      - 'scripts/generate-api-docs.cjs'
      - 'scripts/sync-brand-assets.mjs'
  # Allow manual triggering
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
  pull-requests: write
  issues: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ github.token }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10

      - name: Install root dependencies
        run: npm install

      - name: Resolve n8n stable tag
        id: n8n-tag
        run: echo "tag=$(node scripts/ensure-n8n-cache.cjs --print-tag)" >> "$GITHUB_OUTPUT"

      - name: Cache n8n repository
        uses: actions/cache@v4
        with:
          path: .n8n-cache
          key: ${{ runner.os }}-n8n-cache-${{ steps.n8n-tag.outputs.tag }}-${{ hashFiles('scripts/ensure-n8n-cache.cjs') }}
          restore-keys: |
            ${{ runner.os }}-n8n-cache-

      - name: Build packages
        run: npm run build

      - name: Install docs dependencies
        working-directory: ./docs
        run: npm install

      - name: Generate API documentation
        run: npm run docs:api

      - name: Build documentation
        working-directory: ./docs
        run: npm run build

      - name: Setup Pages
        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
        uses: actions/configure-pages@v4

      - name: Upload artifact
        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs/build

      - name: Run documentation tests
        run: |
          # Check if documentation builds successfully
          if [ ! -d "./docs/build" ]; then
            echo "Documentation build failed - build directory not found"
            exit 1
          fi
          
          # Check for broken links (basic check)
          echo "Checking for broken internal links..."
          # We exclude 404.html because it naturally contains "Page Not Found"
          find ./docs/build -name "*.html" -type f ! -name "404.html" | head -20 | while read file; do
            echo "Checking $file"
            if grep -q "Page Not Found" "$file"; then
              echo "ERROR: Found 'Page Not Found' in $file"
              exit 1
            fi
          done
          
          echo "Documentation build validation passed"

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  # Documentation validation job (runs on PRs)
  validate:
    env:
      GITHUB_TOKEN: ${{ github.token }}
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10

      - name: Install root dependencies
        run: npm install

      - name: Install docs dependencies
        working-directory: ./docs
        run: npm install

      - name: Validate documentation structure
        run: |
          echo "Validating documentation structure..."
          
          # Check required directories exist
          required_dirs=(
            "docs/docs/home"
            "docs/docs/getting-started"
            "docs/docs/usage"
            "docs/docs/contribution"
            "docs/docs/community"
          )
          
          for dir in "${required_dirs[@]}"; do
            if [ ! -d "$dir" ]; then
              echo "ERROR: Required directory $dir not found"
              exit 1
            fi
          done
          
          # Check required configuration files
          required_files=(
            "docs/docusaurus.config.ts"
            "docs/sidebars.ts"
            "docs/sidebars.api.ts"
            "docs/src/css/custom.css"
          )
          
          for file in "${required_files[@]}"; do
            if [ ! -f "$file" ]; then
              echo "ERROR: Required file $file not found"
              exit 1
            fi
          done
          
          echo "Documentation structure validation passed"

      - name: TypeScript type checking
        working-directory: ./docs
        run: npm run typecheck

      - name: Check for broken links in markdown
        run: |
          echo "Checking for broken markdown links..."
          # Install markdown link checker if not present
          if ! command -v markdown-link-check &> /dev/null; then
            npm install -g markdown-link-check
          fi
          
          # Check a subset of markdown files
          find docs/docs -name "*.md" -type f | head -10 | while read file; do
            echo "Checking $file"
            markdown-link-check "$file" --config .github/markdown-link-check-config.json 2>/dev/null || true
          done

      - name: Generate API documentation (dry run)
        run: npm run docs:api -- --dry-run 2>/dev/null || echo "API generation check completed"

      - name: Comment on PR with documentation preview
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const { owner, repo } = context.repo;
            const prNumber = context.payload.pull_request.number;
            
            const success = '${{ job.status }}' === 'success';
            const message = success 
              ? `✅ Documentation validation passed! The documentation changes look good.\n\nOnce merged, the documentation will be automatically deployed to GitHub Pages.`
              : `❌ Documentation validation failed. Please check the workflow logs for details.`;
            
            await github.rest.issues.createComment({
              owner,
              repo,
              issue_number: prNumber,
              body: `## Documentation Validation\n\n${message}\n\n**Workflow:** ${{ github.workflow }} #${{ github.run_id }}`
            });