trilium/.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
      - master  # Also support master branch
    # Only run when docs files change
    paths:
      - 'docs/**'
      - 'README.md'  # README is synced to docs/index.md
      - 'mkdocs.yml'
      - 'requirements-docs.txt'
      - '.github/workflows/deploy-docs.yml'
      - 'scripts/fix-mkdocs-structure.ts'
  
  # Allow manual triggering from Actions tab
  workflow_dispatch:
  
  # Run on pull requests for preview deployments
  pull_request:
    branches:
      - main
      - master
    paths:
      - 'docs/**'
      - 'README.md'  # README is synced to docs/index.md
      - 'mkdocs.yml'
      - 'requirements-docs.txt'
      - '.github/workflows/deploy-docs.yml'
      - 'scripts/fix-mkdocs-structure.ts'

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.13'
          cache: 'pip'
          cache-dependency-path: 'requirements-docs.txt'
      
      - name: Install MkDocs and Dependencies
        run: |
          pip install --upgrade pip
          pip install -r requirements-docs.txt
        env:
          PIP_DISABLE_PIP_VERSION_CHECK: 1
      
      # Setup pnpm before fixing docs structure
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
      
      # Setup Node.js with pnpm
      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '22'
          cache: 'pnpm'
      
      # Install Node.js dependencies for the TypeScript script
      - name: Install Dependencies
        run: |
          pnpm install --frozen-lockfile
      
      - name: Fix Documentation Structure
        run: |
          # Fix duplicate navigation entries by moving overview pages to index.md
          pnpm run chore:fix-mkdocs-structure
      
      - name: Build MkDocs Site
        run: |
          # Build with strict mode but allow expected warnings
          mkdocs build --verbose || {
            EXIT_CODE=$?
            # Check if the only issue is expected warnings
            if mkdocs build 2>&1 | grep -E "WARNING.*(README|not found)" && \
               [ $(mkdocs build 2>&1 | grep -c "ERROR") -eq 0 ]; then
              echo "✅ Build succeeded with expected warnings"
              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"
      
      # Install wrangler globally to avoid workspace issues
      - name: Install Wrangler
        run: |
          npm install -g wrangler
      
      # Deploy using Wrangler (use pre-installed wrangler)
      - 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=trilium-docs --branch=${{ github.ref_name }}
          wranglerVersion: ''  # Use pre-installed version
      
      # 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=trilium-docs --branch=pr-${{ github.event.pull_request.number }}
          wranglerVersion: ''  # Use pre-installed version
      
      # 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
            const previewUrl = `https://pr-${prNumber}.trilium-docs.pages.dev`;
            const mainUrl = 'https://docs.triliumnotes.org';
            
            // 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
              });
            }