Migrate docs site from Jekyll to DocFX

.github/workflows/docfx-gh-pages.yml

@@ -0,0 +1,55 @@
+name: Build and Deploy DocFX
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+
+      - name: Install DocFX tool
+        run: dotnet tool install --tool-path . docfx
+
+      - name: Build multi-version documentation
+        shell: bash
+        run: .github/workflows/scripts/build-docfx.sh
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/scripts/build-docfx.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(pwd)"
+ARTIFACT_DIR="$ROOT/.docfx-artifacts"
+WORKTREE_ROOT="$ROOT/.docfx-worktrees"
+WORKTREES_TO_REMOVE=()
+
+cleanup() {
+  if [ ${#WORKTREES_TO_REMOVE[@]} -gt 0 ]; then
+    for worktree in "${WORKTREES_TO_REMOVE[@]}"; do
+      if [ -d "$worktree" ]; then
+        git worktree remove --force "$worktree" >/dev/null 2>&1 || true
+      fi
+    done
+  fi
+  rm -rf "$ARTIFACT_DIR" "$WORKTREE_ROOT"
+}
+trap cleanup EXIT
+
+rm -rf "$ARTIFACT_DIR" "$WORKTREE_ROOT"
+mkdir -p "$ARTIFACT_DIR" "$WORKTREE_ROOT"
+
+# Verify docfx tool exists
+if [ ! -f "$ROOT/docfx" ]; then
+  echo "Error: docfx tool not found at $ROOT/docfx"
+  echo "Please run: dotnet tool install --tool-path . docfx"
+  exit 1
+fi
+
+./docfx metadata docs/docfx.json
+./docfx build docs/docfx.json
+mv docs/_site "$ARTIFACT_DIR/main"
+
+RELEASE_VERSIONS=()
+RELEASE_TMP="$(mktemp)"
+git ls-remote --heads origin 'rel/v*' >"$RELEASE_TMP"
+if [ -s "$RELEASE_TMP" ]; then
+  git fetch --no-tags origin 'refs/heads/rel/*:refs/remotes/origin/rel/*'
+  mapfile -t RELEASE_VERSIONS < <(git for-each-ref --format='%(refname:short)' refs/remotes/origin/rel | sed 's#^origin/rel/##' | sort -rV)
+fi
+rm -f "$RELEASE_TMP"
+
+LATEST_RELEASE=""
+BUILT_VERSIONS=()
+if [ "${#RELEASE_VERSIONS[@]}" -gt 0 ]; then
+  for version in "${RELEASE_VERSIONS[@]}"; do
+    if [ -z "$version" ]; then
+      continue
+    fi
+
+    branch="origin/rel/$version"
+    worktree="$WORKTREE_ROOT/$version"
+    git worktree add --force "$worktree" "$branch"
+    WORKTREES_TO_REMOVE+=("$worktree")
+
+    # Skip branches without DocFX configuration
+    if [ ! -f "$worktree/docs/docfx.json" ]; then
+      echo "Skipping $version: no DocFX configuration found"
+      git worktree remove --force "$worktree"
+      unset 'WORKTREES_TO_REMOVE[-1]'
+      continue
+    fi
+
+    pushd "$worktree" >/dev/null
+    if "$ROOT/docfx" metadata docs/docfx.json && "$ROOT/docfx" build docs/docfx.json; then
+      popd >/dev/null
+
+      mkdir -p "$ARTIFACT_DIR/$version"
+      cp -a "$worktree/docs/_site/." "$ARTIFACT_DIR/$version/"
+      git worktree remove --force "$worktree"
+      unset 'WORKTREES_TO_REMOVE[-1]'
+
+      BUILT_VERSIONS+=("$version")
+      if [ -z "$LATEST_RELEASE" ]; then
+        LATEST_RELEASE="$version"
+      fi
+    else
+      echo "Failed to build documentation for $version, skipping"
+      popd >/dev/null
+      git worktree remove --force "$worktree"
+      unset 'WORKTREES_TO_REMOVE[-1]'
+    fi
+  done
+fi
+
+rm -rf docs/_site
+mkdir -p docs/_site
+
+if [ -n "$LATEST_RELEASE" ]; then
+  cp -a "$ARTIFACT_DIR/$LATEST_RELEASE/." docs/_site/
+else
+  cp -a "$ARTIFACT_DIR/main/." docs/_site/
+  LATEST_RELEASE="main"
+fi
+
+mkdir -p docs/_site/main
+cp -a "$ARTIFACT_DIR/main/." docs/_site/main/
+
+for version in "${BUILT_VERSIONS[@]}"; do
+  mkdir -p "docs/_site/$version"
+  cp -a "$ARTIFACT_DIR/$version/." "docs/_site/$version/"
+done
+
+if [ "${#BUILT_VERSIONS[@]}" -gt 0 ]; then
+  releases_json="["
+  for version in "${BUILT_VERSIONS[@]}"; do
+    releases_json+="\"$version\",";
+  done
+  releases_json="${releases_json%,}"
+  releases_json+="]"
+else
+  releases_json="[]"
+fi
+
+{
+  printf '{\n'
+  printf '  "latest": "%s",\n' "$LATEST_RELEASE"
+  printf '  "releases": %s,\n' "$releases_json"
+  printf '  "development": "main"\n'
+  printf '}\n'
+} > docs/_site/versions.json

.gitignore

@@ -101,10 +101,19 @@ src/Humanizer.Tests/ApiApprover/PublicApiApprovalTest.approve_public_api.receive
 
 *.received.*
 
-# Jekyll
+# Documentation output
 docs/_site/
 docs/.jekyll-cache/
 docs/.sass-cache/
+docs/.docfx/
+docs/obj/
+docs/api/**.yml
+docs/api/.manifest
+docs/api/.xrefmap.json
+docs/api/.xrefmap.yml
+docfx
+.docfx-artifacts/
+.docfx-worktrees/
 
 # BenchmarkDotNet artifacts
 **/BenchmarkDotNet.Artifacts/

docs/api/index.md

@@ -0,0 +1,7 @@
+# API Reference
+
+The API reference is automatically generated from the `Humanizer` assembly and its XML documentation using DocFX.
+
+Use the table of contents to explore namespaces, types, and members. Each page links back to the corresponding source when available.
+
+The table of contents is generated automatically during the documentation build process and stays in sync with the codebase.