feat(docs): migrate documentation from MkDocs to Docusaurus v3

.github/workflows/docs-deploy.yml

@@ -0,0 +1,100 @@
+name: Deploy Documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main, release]
+    paths:
+      - "docs-site/**"
+      - "docs/**"
+      - ".github/workflows/docs-deploy.yml"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages-deploy"
+  cancel-in-progress: false
+
+env:
+  NODE_VERSION: "20"
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: docs-site
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: "pnpm"
+          cache-dependency-path: docs-site/pnpm-lock.yaml
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Restore Docusaurus cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            docs-site/.docusaurus
+            docs-site/node_modules/.cache
+          key: ${{ runner.os }}-docusaurus-${{ hashFiles('docs-site/pnpm-lock.yaml') }}-${{ hashFiles('docs-site/**/*.{ts,tsx,mdx,css}') }}
+          restore-keys: |
+            ${{ runner.os }}-docusaurus-${{ hashFiles('docs-site/pnpm-lock.yaml') }}-
+            ${{ runner.os }}-docusaurus-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Sync docs content
+        run: pnpm run sync-docs
+
+      - name: Build LLMs.txt
+        run: pnpm run build:llms-txt
+
+      - name: Build documentation
+        run: pnpm build
+        env:
+          NODE_OPTIONS: "--max-old-space-size=4096"
+          POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
+          POSTHOG_HOST: ${{ secrets.POSTHOG_HOST }}
+          ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
+          ALGOLIA_SEARCH_API_KEY: ${{ secrets.ALGOLIA_SEARCH_API_KEY }}
+          GA_TRACKING_ID: ${{ secrets.GA_TRACKING_ID }}
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docs-pr-validation.yml

@@ -0,0 +1,184 @@
+name: Documentation PR Validation
+
+on:
+  pull_request:
+    branches: [main, release]
+    paths:
+      - "docs-site/**"
+      - "docs/**"
+      - ".github/workflows/docs-pr-validation.yml"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  NODE_VERSION: "20"
+
+jobs:
+  validate:
+    name: Validate Documentation
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-site
+    outputs:
+      frontmatter_status: ${{ steps.frontmatter.outcome }}
+      typecheck_status: ${{ steps.typecheck.outcome }}
+      build_status: ${{ steps.build.outcome }}
+      links_status: ${{ steps.links.outcome }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: "pnpm"
+          cache-dependency-path: docs-site/pnpm-lock.yaml
+
+      - name: Restore Docusaurus cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            docs-site/.docusaurus
+            docs-site/node_modules/.cache
+          key: ${{ runner.os }}-docusaurus-${{ hashFiles('docs-site/pnpm-lock.yaml') }}-${{ hashFiles('docs-site/**/*.{ts,tsx,mdx,css}') }}
+          restore-keys: |
+            ${{ runner.os }}-docusaurus-${{ hashFiles('docs-site/pnpm-lock.yaml') }}-
+            ${{ runner.os }}-docusaurus-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Sync docs content
+        run: pnpm run sync-docs
+
+      - name: Validate frontmatter
+        id: frontmatter
+        continue-on-error: true
+        run: pnpm run validate:frontmatter
+
+      - name: TypeScript check
+        id: typecheck
+        run: pnpm run typecheck
+
+      - name: Build documentation
+        id: build
+        run: pnpm build
+        env:
+          NODE_OPTIONS: "--max-old-space-size=4096"
+
+      - name: Validate links
+        id: links
+        continue-on-error: true
+        run: |
+          if grep -q '"validate:links"' package.json; then
+            pnpm run validate:links
+          else
+            echo "No validate:links script found, skipping..."
+          fi
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-build-${{ github.sha }}
+          path: docs-site/build
+          retention-days: 7
+
+  comment:
+    name: Post Validation Results
+    runs-on: ubuntu-latest
+    needs: validate
+    if: always()
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Post PR comment with results
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const frontmatter = '${{ needs.validate.outputs.frontmatter_status }}';
+            const typecheck = '${{ needs.validate.outputs.typecheck_status }}';
+            const build = '${{ needs.validate.outputs.build_status }}';
+            const links = '${{ needs.validate.outputs.links_status }}';
+
+            const getStatusEmoji = (status) => {
+              if (status === 'success') return ':white_check_mark:';
+              if (status === 'failure') return ':x:';
+              if (status === 'skipped') return ':fast_forward:';
+              return ':warning:';
+            };
+
+            const getStatusText = (status) => {
+              if (status === 'success') return 'Passed';
+              if (status === 'failure') return 'Failed';
+              if (status === 'skipped') return 'Skipped';
+              return 'Unknown';
+            };
+
+            const allPassed = frontmatter === 'success' &&
+                             typecheck === 'success' &&
+                             build === 'success';
+
+            const overallStatus = allPassed
+              ? ':rocket: **Documentation validation passed!**'
+              : ':warning: **Documentation validation has issues**';
+
+            const body = `## Documentation Validation Results
+
+            ${overallStatus}
+
+            | Check | Status | Result |
+            |-------|--------|--------|
+            | Frontmatter Validation | ${getStatusEmoji(frontmatter)} | ${getStatusText(frontmatter)} |
+            | TypeScript Check | ${getStatusEmoji(typecheck)} | ${getStatusText(typecheck)} |
+            | Build | ${getStatusEmoji(build)} | ${getStatusText(build)} |
+            | Link Validation | ${getStatusEmoji(links)} | ${getStatusText(links)} |
+
+            ---
+
+            ${allPassed
+              ? ':package: Build artifact uploaded successfully. Ready for deployment preview.'
+              : ':construction: Please fix the failing checks before merging.'}
+
+            <sub>Commit: \`${{ github.sha }}\` | Workflow: [View logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})</sub>
+            `;
+
+            // Find existing comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
+              comment.body.includes('Documentation Validation Results')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: body
+              });
+            }