Migrate docs site from Jekyll to DocFX

.config/dotnet-tools.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.78.4",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
+    }
+  }
+}

.github/CONTRIBUTING.md

@@ -10,7 +10,7 @@ to clarify expected behavior in our community.
 For more information see the [.NET Foundation Code of Conduct](http://www.dotnetfoundation.org/code-of-conduct).
 
 ### <a id="getting-started">Getting started</a>
-This project uses C# 8 language features and SDK-style projects, so you'll need any edition of [Visual Studio 2019](https://www.visualstudio.com/downloads/download-visual-studio-vs) to open and compile the project. The free [Community Edition](https://go.microsoft.com/fwlink/?LinkId=532606&clcid=0x409) will work.
+This project uses C# 14 language features and SDK-style projects, so you'll need .NET 10 SDK to compile.
 
 ### <a id="contribution-guideline">Contribution guideline</a>
 This project uses [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html) for pull requests.

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

@@ -0,0 +1,70 @@
+name: Build and Deploy Docs
+
+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: Restore .NET tools
+        run: dotnet tool restore
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install Docusaurus dependencies
+        working-directory: website
+        run: npm ci
+
+      - name: Build DocFX API versions
+        shell: bash
+        run: .github/workflows/scripts/build-docfx.sh
+
+      - name: Build Docusaurus site
+        working-directory: website
+        run: npm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/build
+
+  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,127 @@
+#!/bin/bash
+
+set -euo pipefail
+
+ROOT="$(pwd)"
+ARTIFACT_DIR="$ROOT/.docfx-artifacts"
+WORKTREE_ROOT="$ROOT/.docfx-worktrees"
+STATIC_API_DIR="$ROOT/website/static/api"
+WORKTREES_TO_REMOVE=()
+DOCFX_CMD="dotnet tool run docfx"
+
+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"
+
+build_docfx_for_checkout() {
+  local checkout_root="$1"
+  local destination_name="$2"
+
+  pushd "$checkout_root" >/dev/null
+  $DOCFX_CMD metadata docs/docfx.json
+  $DOCFX_CMD build docs/docfx.json
+  popd >/dev/null
+
+  mkdir -p "$ARTIFACT_DIR/$destination_name"
+  cp -a "$checkout_root/docs/_site/." "$ARTIFACT_DIR/$destination_name/"
+}
+
+# Build current checkout (development)
+build_docfx_for_checkout "$ROOT" "main"
+rm -rf "$ROOT/docs/_site"
+
+# Discover release branches
+RELEASE_VERSIONS=()
+SKIP_FETCH="${SKIP_RELEASE_FETCH:-0}"
+
+if [ "$SKIP_FETCH" != "1" ]; then
+  RELEASE_TMP="$(mktemp)"
+  if git ls-remote --heads origin 'rel/v*' >"$RELEASE_TMP"; then
+    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
+  else
+    echo "Warning: unable to query release branches; continuing with development API only."
+  fi
+  rm -f "$RELEASE_TMP"
+else
+  echo "Skipping release branch builds per SKIP_RELEASE_FETCH=$SKIP_FETCH"
+fi
+
+LATEST_RELEASE=""
+BUILT_RELEASES=()
+
+for version in "${RELEASE_VERSIONS[@]}"; do
+  [ -n "$version" ] || continue
+
+  branch="origin/rel/$version"
+  worktree="$WORKTREE_ROOT/$version"
+  git worktree add --force "$worktree" "$branch"
+  WORKTREES_TO_REMOVE+=("$worktree")
+
+  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
+
+  if build_docfx_for_checkout "$worktree" "$version"; then
+    BUILT_RELEASES+=("$version")
+    if [ -z "$LATEST_RELEASE" ]; then
+      LATEST_RELEASE="$version"
+    fi
+  else
+    echo "Failed to build documentation for $version, skipping"
+  fi
+
+  git worktree remove --force "$worktree" || true
+  unset 'WORKTREES_TO_REMOVE[-1]'
+done
+
+rm -rf "$STATIC_API_DIR"
+mkdir -p "$STATIC_API_DIR"
+
+cp -a "$ARTIFACT_DIR/main/." "$STATIC_API_DIR/main/"
+
+for version in "${BUILT_RELEASES[@]}"; do
+  mkdir -p "$STATIC_API_DIR/$version"
+  cp -a "$ARTIFACT_DIR/$version/." "$STATIC_API_DIR/$version/"
+done
+
+if [ -n "$LATEST_RELEASE" ]; then
+  DEFAULT_RELEASE="$LATEST_RELEASE"
+else
+  DEFAULT_RELEASE="main"
+fi
+
+if [ "${#BUILT_RELEASES[@]}" -gt 0 ]; then
+  releases_json="["
+  for version in "${BUILT_RELEASES[@]}"; do
+    releases_json+="\"$version\",";
+  done
+  releases_json="${releases_json%,}]"
+else
+  releases_json="[]"
+fi
+
+cat >"$STATIC_API_DIR/versions.json" <<MANIFEST
+{
+  "latest": "$DEFAULT_RELEASE",
+  "releases": $releases_json,
+  "development": "main"
+}
+MANIFEST

.gitignore

@@ -101,10 +101,27 @@ 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/
+**/BenchmarkDotNet.Artifacts/
+
+# Docusaurus artifacts
+website/.docusaurus/
+website/build/
+website/node_modules/
+website/static/api/**
+!website/static/api
+!website/static/api/.gitkeep

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/memories/code_style_conventions.md

@@ -0,0 +1,8 @@
+- Use `.editorconfig` defaults: spaces, 4-space indentation, file-scoped namespaces, trim redundant blank lines.
+- Prefer language keywords (`string`, `int`) and `var` when the type is obvious. Avoid unnecessary `this.` qualifiers.
+- Order `using` statements with `System.*` first; rely on existing global usings.
+- Keep code self-documenting; comments are rare and reserved for non-obvious logic. Never wrap imports in `try/catch`.
+- Follow Humanizer naming conventions (camelCase private fields, PascalCase public members/static readonly/constants).
+- Skip braces for single-line statements when consistent with surrounding code.
+- Add XML documentation for any new or modified public APIs and update README/docs when behavior changes.
+- Tests: organize with xUnit, group by feature/culture, use `UseCulture` attribute for localization-specific assertions.

.serena/memories/project_overview.md

@@ -0,0 +1,12 @@
+- **Purpose:** Humanizer is a .NET library that converts numbers, dates, times, enums, quantities, strings, and collections into human-friendly text across 40+ locales. Primary code lives in `src/Humanizer`; validation happens in `src/Humanizer.Tests`.
+- **Tech stack:** C# targeting .NET 10.0/9.0/8.0 and .NET Framework 4.8 (plus .NET Standard 2.0 for analyzers). Uses xUnit for tests, DocFX for docs, Azure DevOps for CI, and optional analyzers under `src/Humanizer.Analyzers`.
+- **Repo layout:**
+  - `src/Humanizer` – main library, resources, configuration.
+  - `src/Humanizer.Tests` – xUnit suites organized by feature/culture (uses `UseCulture`).
+  - `src/Humanizer.Analyzers` + `.Tests` – Roslyn analyzers and coverage.
+  - `src/Benchmarks` – perf harness.
+  - `docs`/`docfx3` – documentation site built with DocFX.
+  - `NuSpecs`, `version.json`, `verify-packages.ps1` – packaging/release assets.
+- **Key guidelines:** Follow `.editorconfig`, modern C#, file-scoped namespaces, `var` for obvious types, System usings first, minimal comments, no `try/catch` around imports, XML docs for public APIs, update README/docs when behavior changes.
+- **Localization:** Cultures live under `src/Humanizer/Properties`; register new formatters in registry classes and add localized tests under `src/Humanizer.Tests/Localisation/<culture>`.
+- **Docs & samples:** Build via `dotnet tool run docfx` commands in README; samples under `samples/Humanizer.MvcSample` (legacy MVC example).

.serena/memories/suggested_commands.md

@@ -0,0 +1,27 @@
+```bash
+# Inspect repo status / files (Linux environment)
+git status
+ls -a
+rg "search term"
+
+# Restore + build
+cd /home/claire/local-dev/Humanizer/src
+DOTNET_CLI_UI_LANGUAGE=en dotnet restore
+DOTNET_CLI_UI_LANGUAGE=en dotnet build Humanizer/Humanizer.csproj -c Release /t:PackNuSpecs /p:PackageOutputPath=<out>
+
+# Run tests (Linux skips net48)
+dotnet test src/Humanizer.Tests/Humanizer.Tests.csproj --framework net10.0
+dotnet test src/Humanizer.Tests/Humanizer.Tests.csproj --framework net8.0
+
+# Verify packages after building
+pwsh ./verify-packages.ps1 -PackagesPath <out> -MinimumPassingSdkVersion 9.0.200
+
+# DocFX docs (from repo root)
+dotnet tool restore
+dotnet tool run docfx build docs/docfx.json
+# Preview docs
+dotnet tool run docfx serve docs/_site
+
+# Benchmarks (example)
+dotnet run --project src/Benchmarks/Benchmarks.csproj -c Release
+```

.serena/memories/task_completion.md

@@ -0,0 +1,7 @@
+- Ensure dotnet test passes for net10.0 and net8.0 (`src/Humanizer.Tests/Humanizer.Tests.csproj`). Avoid running net48 on Linux.
+- When applicable, run `dotnet build Humanizer/Humanizer.csproj -c Release /t:PackNuSpecs` (from `src`) to confirm packaging stays healthy.
+- Update or add xUnit tests alongside code changes, including culture-specific suites.
+- Refresh docs/README or XML summaries when altering behavior, locales, or APIs. Regenerate DocFX content if needed (`dotnet tool run docfx build docs/docfx.json`).
+- For localization additions, duplicate resource files, register formatters, and add tests in `src/Humanizer.Tests/Localisation/<culture>`.
+- After packaging, optionally run `verify-packages.ps1` with the package output path and minimum SDK (default 9.0.200).
+- Confirm `git status` shows only intended changes before handing off or creating a PR.