fix: 🐛 add gh-pages branch initialization and update Docusaurus config for deployment

gracefullight · gracefullight · commit b713486c984a · 2025-09-08T18:45:35.000+10:00
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -3,6 +3,7 @@ name: Deploy Docs
 on:
   push:
     branches: ["main"]
+  workflow_dispatch: {}
 
 # Branch-based Pages deployment via `docusaurus deploy`
 permissions:
@@ -24,6 +25,23 @@ jobs:
           node-version: 22
           cache: "pnpm"
       - run: pnpm install --frozen-lockfile
+      - name: Ensure gh-pages branch exists
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then
+            echo "gh-pages branch exists"
+          else
+            echo "Initializing gh-pages branch"
+            git switch --orphan gh-pages
+            git rm -rf . || true
+            echo '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=/docusaurus-plugins/">' > index.html
+            git add -A
+            git commit -m "chore: initialize gh-pages"
+            git push origin gh-pages
+            git switch -
+          fi
       - name: Configure git identity
         run: |
           git config user.name "github-actions[bot]"
diff --git a/apps/docs/docusaurus.config.ts b/apps/docs/docusaurus.config.ts
@@ -17,6 +17,8 @@ const themeConfig: ThemeConfig = {
 
 const config: Config = {
   baseUrl: "/docusaurus-plugins/",
+  // Ensure branch-based GH Pages deploys target the right branch
+  deploymentBranch: "gh-pages",
   favicon: "img/favicon.ico",
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "warn",
@@ -36,6 +38,8 @@ const config: Config = {
   projectName: "docusaurus-plugins",
   themeConfig,
   title: "docusaurus-plugins",
+  // Set explicit trailingSlash for GitHub Pages to avoid redirect quirks
+  trailingSlash: true,
   url: "https://gracefullight.github.io",
 };
 
