readur/.github/workflows/deploy-docs.yml

# GitHub Actions workflow for deploying MkDocs documentation to Cloudflare Pages
# This workflow builds and deploys your MkDocs site when changes are pushed to main
name: Deploy MkDocs Documentation

on:
  # Trigger on push to main branch
  push:
    branches:
      - main
    # Only run when docs files change
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'requirements.txt'
      - '.github/workflows/deploy-docs.yml'
  
  # Allow manual triggering from Actions tab
  workflow_dispatch:
  
  # Run on pull requests for preview deployments
  pull_request:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'requirements.txt'
      - '.github/workflows/deploy-docs.yml'

jobs:
  build-and-deploy:
    name: Build and Deploy MkDocs
    runs-on: ubuntu-latest
    timeout-minutes: 10
    
    # Required permissions for deployment
    permissions:
      contents: read
      deployments: write
      pull-requests: write # For PR preview comments
      id-token: write # For OIDC authentication (if needed)
    
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5
        with:
          fetch-depth: 0 # Fetch all history for git info and mkdocs-git-revision-date plugin
      
      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.14'
          cache: 'pip'
          cache-dependency-path: 'requirements.txt'
      
      - name: Install MkDocs and Dependencies
        run: |
          pip install --upgrade pip
          pip install -r requirements.txt
        env:
          PIP_DISABLE_PIP_VERSION_CHECK: 1
      
      - name: Build MkDocs Site
        run: |
          # Build with strict mode but ignore the expected README.md warning
          # MkDocs always warns when README.md exists alongside index.md
          mkdocs build --strict --verbose || {
            EXIT_CODE=$?
            # Check if the only issue is the README.md conflict
            if mkdocs build --strict 2>&1 | grep -q "WARNING.*README.md.*conflicts with.*index.md" && \
               [ $(mkdocs build --strict 2>&1 | grep -c "WARNING") -eq 1 ]; then
              echo "✅ Build succeeded with expected README.md warning"
              mkdocs build --verbose
            else
              echo "❌ Build failed with unexpected errors"
              exit $EXIT_CODE
            fi
          }
      
      - name: Validate Built Site
        run: |
          # Basic validation that important files exist
          test -f site/index.html || (echo "ERROR: site/index.html not found" && exit 1)
          test -f site/sitemap.xml || (echo "ERROR: site/sitemap.xml not found" && exit 1)
          test -d site/assets || (echo "ERROR: site/assets directory not found" && exit 1)
          echo "✅ Site validation passed"
      
      # Deploy using Wrangler (recommended by Cloudflare)
      - name: Deploy to Cloudflare Pages
        id: deploy
        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy site --project-name=readur-docs --branch=${{ github.ref_name }}
      
      # Deploy preview for PRs
      - name: Deploy Preview to Cloudflare Pages
        id: preview-deployment
        if: github.event_name == 'pull_request'
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy site --project-name=readur-docs --branch=pr-${{ github.event.pull_request.number }}
      
      # Post deployment URL as PR comment
      - name: Comment PR with Preview URL
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v8
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const prNumber = context.issue.number;
            // Construct preview URL based on Cloudflare Pages pattern
            // Note: Actual URL may vary based on Cloudflare configuration
            const previewUrl = `https://pr-${prNumber}.readur-docs.pages.dev`;
            const mainUrl = 'https://readur.app';
            
            // Check if we already commented
            const comments = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: prNumber
            });
            
            const botComment = comments.data.find(comment => 
              comment.user.type === 'Bot' && 
              comment.body.includes('Documentation preview is ready')
            );
            
            const commentBody = `📚 Documentation preview is ready!\n\n🔗 Preview URL: ${previewUrl}\n📖 Production URL: ${mainUrl}\n\n✅ All checks passed\n\n_This preview will be updated automatically with new commits._`;
            
            if (botComment) {
              // Update existing comment
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: botComment.id,
                body: commentBody
              });
            } else {
              // Create new comment
              await github.rest.issues.createComment({
                issue_number: prNumber,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: commentBody
              });
            }