feat(docs): let's try to deploy our stuff to mkdocs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,151 @@
+# 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/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.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
+      - master
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.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@v5
+        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
+      
+      - 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"
+      
+      # 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=trilium-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=trilium-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@v7
+        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.trilium.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
+              });
+            }