fix(docs): compile Jekyll docs site and add root redirect in CI (#5526)

.agent_memory/session_context.md

@@ -3,6 +3,12 @@
 # Do NOT edit or remove previous entries — stale state claims cause agent confusion.
 # Format: ## YYYY-MM-DD — <summary>
 
+## 2026-05-20 — Fixed Jekyll documentation site build and deployment in CI
+- Created `docs/index.html` to automatically redirect root path requests (`/`) to the English directory (`/en/`).
+- Updated `.github/workflows/docs-deploy.yml` to compile the Jekyll root site using `--baseurl /${{ github.event.repository.name }}` and setup Ruby with version `4.0.4` to match project release workflow conventions.
+- Updated `.github/workflows/docs-release.yml` to compile both versioned and root Jekyll sites, assemble them into `build/final_site/` with Dokka HTML references, configure correct baseurls respectively, and setup Ruby with version `4.0.4`.
+- Verified that local Gradle docs tasks (`generateDocsBundle`, `validateDocsBundle`, `publishDocsSite`) compile successfully and the redirect file is correctly populated in the output.
+
 ## 2026-05-20 — Optimized slow Flatpak CI jobs
 - Restrained flatpakGradleGenerator to target only the runtimeClasspath configuration in desktopApp and build-logic:convention modules.
 - Updated release.yml and reusable-check.yml to invoke only targeted tasks (:desktopApp:flatpakGradleGenerator and :build-logic:convention:flatpakGradleGenerator) instead of running the task on the root and all subprojects.

.github/workflows/docs-deploy.yml

@@ -48,18 +48,33 @@ jobs:
       - name: Build Dokka HTML documentation
         run: ./gradlew dokkaGeneratePublicationHtml --no-configuration-cache
 
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0.4'
+          bundler-cache: true
+          working-directory: docs
+
       - name: Generate Docs Site
         run: ./gradlew generateDocsBundle validateDocsBundle publishDocsSite -Pdocs.channel=root -Pci=true
 
+      - name: Compile Jekyll Docs Site
+        run: |
+          BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build \
+            --source build/_site \
+            --destination build/jekyll_site \
+            --baseurl /${{ github.event.repository.name }}
+          touch build/jekyll_site/.nojekyll
+
       - name: Assemble Pages artifact
         run: |
-          # Copy Dokka output into _site/api/
-          cp -r build/dokka/html build/_site/api
+          # Copy Dokka output into compiled jekyll_site/api/
+          cp -r build/dokka/html build/jekyll_site/api
 
       - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@v5
         with:
-          path: build/_site/
+          path: build/jekyll_site/
 
   deploy:
     if: github.repository == 'meshtastic/Meshtastic-Android'

.github/workflows/docs-release.yml

@@ -38,6 +38,13 @@ jobs:
         with:
           gradle_encryption_key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
 
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0.4'
+          bundler-cache: true
+          working-directory: docs
+
       # Build root docs site (/ on Pages)
       - name: Build Root Docs Site
         run: ./gradlew generateDocsBundle publishDocsSite -Pdocs.channel=root -Pci=true
@@ -50,17 +57,45 @@ jobs:
       - name: Build Dokka HTML documentation
         run: ./gradlew dokkaGeneratePublicationHtml --no-configuration-cache
 
+      - name: Compile Jekyll Sites
+        run: |
+          # Build versioned Jekyll site
+          BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build \
+            --source build/_site/v${{ steps.version.outputs.version }} \
+            --destination build/jekyll_release \
+            --baseurl /${{ github.event.repository.name }}/v${{ steps.version.outputs.version }}
+          
+          # Move versioned source folder out of root source folder to avoid nested build issues
+          mv build/_site/v${{ steps.version.outputs.version }} build/v_temp
+
+          # Build root Jekyll site
+          BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build \
+            --source build/_site \
+            --destination build/jekyll_root \
+            --baseurl /${{ github.event.repository.name }}
+
       - name: Assemble Pages artifact
         run: |
-          # Root site is already at build/_site/ from the root channel build.
-          # Versioned docs are at build/_site/v{version}/ from the release channel build.
-          # Add Dokka at /api/
-          cp -r build/dokka/html build/_site/api
+          # Create final site directory
+          mkdir -p build/final_site
+          
+          # Copy root compiled site
+          cp -r build/jekyll_root/* build/final_site/
+          
+          # Copy release compiled site to vX.Y.Z/
+          mkdir -p build/final_site/v${{ steps.version.outputs.version }}
+          cp -r build/jekyll_release/* build/final_site/v${{ steps.version.outputs.version }}/
+          
+          # Copy Dokka output into final_site/api/
+          cp -r build/dokka/html build/final_site/api
+          
+          # Disable GitHub Pages' own Jekyll build
+          touch build/final_site/.nojekyll
 
       - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@v5
         with:
-          path: build/_site/
+          path: build/final_site/
 
   deploy:
     if: github.repository == 'meshtastic/Meshtastic-Android'

docs/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Redirecting...</title>
+  <link rel="canonical" href="en/">
+  <script>location="en/"</script>
+  <meta http-equiv="refresh" content="0; url=en/">
+</head>
+<body>
+  <p>Redirecting to <a href="en/">en/</a>...</p>
+</body>
+</html>