docs: migrate documentation site from Jekyll to Docusaurus (#27)

## Summary
Migrates the documentation site from Jekyll (GitHub Pages theme) to
Docusaurus 3, modernizing the build toolchain and improving the
developer experience for documentation maintenance.

## Key Changes

- **Replaced Jekyll with Docusaurus**: Removed `_config.yml` and
Jekyll-specific configuration; added `docusaurus.config.ts` with full
Docusaurus 3.6.3 setup including theme configuration, navbar, and footer
- **Updated documentation metadata**: Converted Jekyll front matter
(`nav_order`, `parent`, `permalink`) to Docusaurus format
(`sidebar_position`, `slug`) across all markdown files
- **Added sidebar configuration**: Created `sidebars.ts` with
autogenerated sidebar structure and `_category_.json` files for
organizing Guides and Components sections
- **Updated internal links**: Converted Jekyll Liquid template syntax
(`{{ '/path/' | relative_url }}`) to Docusaurus-compatible paths
(`/path`)
- **Added styling**: Created `src/css/custom.css` with light/dark theme
color variables and diagram styling, replacing Jekyll's
`_includes/head_custom.html`
- **Updated CI/CD workflow**: Renamed and refactored
`.github/workflows/jekyll-gh-pages.yml` to `docusaurus-gh-pages.yml`
with Node.js setup, npm dependency installation, and Docusaurus build
steps
- **Added package.json**: Created `docs/package.json` with Docusaurus
dependencies and npm scripts for local development (`npm start`) and
production builds
- **Updated diagram rendering**: Modified `docs/diagrams/render.sh` to
output SVG files to `docs/static/diagrams/` for Docusaurus static asset
serving
- **Added TypeScript config**: Created `tsconfig.json` extending
Docusaurus TypeScript configuration

## Notable Implementation Details

- Docusaurus is configured to serve docs at the root path (`/`) with
GitHub Pages base URL `/game-server-deploy/`
- Mermaid diagram support is enabled via `@docusaurus/theme-mermaid`
theme
- Color scheme respects user OS preference with separate light/dark
theme variables
- D2 diagram SVG files are pre-rendered during CI and served as static
assets
- Documentation can now be previewed locally with `cd docs && npm
install && npm start`

https://claude.ai/code/session_011UQT9Yu7T3U3393WiDXemb

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: 3 people

.github/workflows/docs-build.yml

@@ -0,0 +1,40 @@
+name: Docs build check
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs-build.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install D2
+        run: |
+          curl -fsSL https://d2lang.com/install.sh | sh -s -- --prefix "$HOME/.local"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Render D2 diagrams
+        run: bash docs/diagrams/render.sh
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Build
+        run: npm run build
+        working-directory: docs

.github/workflows/jekyll-gh-pages.yml .github/workflows/docusaurus-gh-pages.yml.github/workflows/jekyll-gh-pages.yml renamed to .github/workflows/docusaurus-gh-pages.yml

@@ -1,55 +1,61 @@
-name: Deploy Docs
+name: Deploy Docusaurus docs site to GitHub Pages
 
 on:
-  # Runs on pushes targeting the default branch that touch the docs site
-  # (or this workflow itself).
   push:
     branches: ["main"]
     paths:
       - "docs/**"
-      - ".github/workflows/jekyll-gh-pages.yml"
+      - ".github/workflows/docusaurus-gh-pages.yml"
 
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  # Build job
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
       - name: Install D2
         run: |
           curl -fsSL https://d2lang.com/install.sh | sh -s -- --prefix "$HOME/.local"
           echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
       - name: Render D2 diagrams
-        run: docs/diagrams/render.sh
+        run: bash docs/diagrams/render.sh
+
+      - name: Install Docusaurus dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Build Docusaurus site
+        run: npm run build
+        working-directory: docs
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: ./docs
-          destination: ./_site
-      - name: Fix _site permissions
-        run: sudo chmod -R +rX _site/
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
 
-  # Deployment job
   deploy:
     environment:
       name: github-pages

docs/.gitignore

@@ -0,0 +1,4 @@
+# Docusaurus generated outputs — not committed
+.docusaurus/
+build/
+node_modules/

docs/_config.yml

@@ -1,12 +1,16 @@
 #!/usr/bin/env bash
-# Render every .d2 source file in this directory to SVG next to it.
-# Run in CI (.github/workflows/jekyll-gh-pages.yml) before Jekyll builds;
-# run locally before `bundle exec jekyll serve` if you want to preview.
+# Render every .d2 source file in this directory to SVG.
+# Output goes to docs/static/diagrams/ so Docusaurus serves them at /diagrams/*.svg.
+# Run in CI (docusaurus-gh-pages.yml) before `npm run build`; run locally
+# before `npm start` if you want to preview diagram changes.
 set -euo pipefail
-cd "$(dirname "$0")"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+OUT_DIR="$SCRIPT_DIR/../static/diagrams"
+mkdir -p "$OUT_DIR"
+cd "$SCRIPT_DIR"
 shopt -s nullglob
 for f in *.d2; do
-  out="${f%.d2}.svg"
+  out="$OUT_DIR/${f%.d2}.svg"
   echo "rendering $f -> $out"
   d2 "$f" "$out"
 done

docs/_includes/head_custom.html

@@ -1,6 +1,6 @@
 ---
 title: Architecture
-nav_order: 2
+sidebar_position: 2
 ---
 
 # Architecture
@@ -35,7 +35,7 @@ ECS / DynamoDB / Secrets Manager / CloudWatch via SDK v3. Players reach
 the game either direct to the task's public IP (UDP / TCP games) or
 through the ALB (HTTPS games).
 
-![Game plane and operator]({{ '/diagrams/game-plane.svg' | relative_url }}){:.d2-diagram}
+![Game plane and operator](/diagrams/game-plane.svg)
 
 ### Serverless Discord bot
 
@@ -45,7 +45,7 @@ it verifies the Ed25519 signature, replies with a deferred ack within
 Discord's 3-second budget, then fires the async `followup` Lambda for
 anything that touches ECS.
 
-![Serverless Discord bot]({{ '/diagrams/discord-bot.svg' | relative_url }}){:.d2-diagram}
+![Serverless Discord bot](/diagrams/discord-bot.svg)
 
 ### Control loops (DNS + watchdog)
 
@@ -56,15 +56,15 @@ pending-interaction row in DynamoDB. `watchdog` fires on a schedule and
 stops tasks whose `NetworkPacketsIn` has stayed below the threshold for
 `IDLE_CHECKS` consecutive intervals.
 
-![Control loops]({{ '/diagrams/control-loops.svg' | relative_url }}){:.d2-diagram}
+![Control loops](/diagrams/control-loops.svg)
 
 ## The `/server-start` critical path
 
 When a user types `/server-start palworld` in Discord, five AWS services and
 three Lambdas cooperate to return a usable `palworld.yourdomain.com` without
 ever letting the interaction time out.
 
-![/server-start sequence]({{ '/diagrams/server-start.svg' | relative_url }}){:.d2-diagram}
+![/server-start sequence](/diagrams/server-start.svg)
 
 After the session: either the user types `/server-stop palworld` (same flow
 but `stopTask` + `DELETE` A record), or the Watchdog Lambda notices
@@ -110,5 +110,5 @@ write the PR description as if you're explaining the new design.
    the idle counter — it is an `idle_checks` tag on each running task.
    Counter resets when a task stops, which is free.
 
-See the [maintainer guide]({{ '/guides/maintainer/' | relative_url }}) for
+See the [maintainer guide](/guides/maintainer) for
 what tends to break these and what the failure modes look like.

docs/diagrams/render.sh

@@ -0,0 +1,8 @@
+{
+  "label": "Components",
+  "position": 5,
+  "link": {
+    "type": "doc",
+    "id": "components/index"
+  }
+}

docs/architecture.md docs/docs/architecture.mddocs/architecture.md renamed to docs/docs/architecture.md

@@ -1,20 +1,19 @@
 ---
 title: Components
-nav_order: 5
-has_children: true
+sidebar_position: 1
 ---
 
 # Components
 
 Deep-dives on each piece of the stack, for when the guides hand-wave past
 something:
 
-- **[Terraform]({{ '/components/terraform/' | relative_url }})** — every
+- **[Terraform](/components/terraform)** — every
   `.tf` file, variables, outputs, and AWS services touched.
-- **[Management app]({{ '/components/management-app/' | relative_url }})** —
+- **[Management app](/components/management-app)** —
   the Nest.js API, React dashboard, and `@gsd/shared` library.
-- **[Lambdas]({{ '/components/lambdas/' | relative_url }})** — the four
+- **[Lambdas](/components/lambdas)** — the four
   Node.js Lambdas (interactions, followup, update-dns, watchdog).
 
 For the big picture, start at the
-[architecture overview]({{ '/architecture/' | relative_url }}).
+[architecture overview](/architecture).

docs/docs/components/_category_.json

@@ -1,7 +1,6 @@
 ---
 title: Lambdas
-parent: Components
-nav_order: 3
+sidebar_position: 4
 ---
 
 # Lambdas
@@ -127,7 +126,7 @@ Event shape (simplified):
 ```json
 {
   "detail": {
-    "lastStatus": "RUNNING" | "STOPPED",
+    "lastStatus": "RUNNING | STOPPED",
     "taskArn": "...",
     "clusterArn": "...",
     "group": "family:palworld-server"
@@ -204,7 +203,7 @@ Failure modes:
 
 ## The `/server-start` critical path, assembled
 
-```
+```text
 User types /server-start palworld
   → Discord POSTs to interactions Function URL
     → interactions verifies + returns type:5 ack + async-invokes followup