Migrate docs site from Jekyll to DocFX #1642

clairernovotny · 2025-11-06T03:17:56Z

This pull request introduces a major overhaul to the documentation build and deployment process, switching from Jekyll/GitHub Pages to DocFX for multi-version API documentation. It adds a GitHub Actions workflow to automate building and deploying documentation for both the main branch and release branches, generates a comprehensive API reference, and provides new integration guides for using Humanizer in various .NET application types. The old Jekyll configuration and layouts are removed to support this migration.

DocFX migration and automation:

Added .github/workflows/docfx-gh-pages.yml to automate building and deploying DocFX-based documentation to GitHub Pages, supporting both main and release branches for multi-version docs.
Added .github/workflows/scripts/build-docfx.sh to build documentation for all release branches using Git worktrees, aggregate results, and generate a versions.json manifest for the site.

Documentation content updates:

Added docs/api/index.md and docs/api/toc.yml to provide a generated API reference for the Humanizer assembly, including a detailed table of contents for namespaces, types, and members. [1] [2]
Added docs/application-integration.md, a comprehensive guide on integrating Humanizer into web, desktop, background, CLI, and logging scenarios, including code samples and best practices.
Added docs/assets/README.md to describe the purpose of the documentation assets folder for DocFX resources.

Removal of legacy Jekyll files:

Removed Jekyll configuration and layout files (docs/_config.yml and docs/_layouts/default.html) as part of the migration to DocFX. [1] [2]

- Remove Jekyll site files (docs/_config.yml, _layouts/default.html, assets/style.css) - Add DocFX config and inputs (docs/docfx.json, docs/api/, docs/toc.yml and many new documentation pages) - Add GitHub Actions workflow to build & deploy DocFX site (.github/workflows/docfx-gh-pages.yml) - Update README and in-repo docs to reference DocFX-driven documentation and new doc paths - Add docs assets placeholder and documentation content (application-integration, configuration, numbers, dates-and-times, performance, testing, troubleshooting, etc.) - Update .gitignore to exclude DocFX build/worktree/artifacts and generated API YAML files Prepare repository for DocFX-based multi-version documentation and GitHub Pages deployment.

- application-integration: remove optional global using lines and add a concrete HumanizingMetadataProvider example + registration. - collection-humanization: add culture-keyed collection formatter example and full Oxford-style implementation; recommend startup registration. - configuration: expand Configurator examples (formatters, collection formatters, number converters), clarify strategy/registry usage, testing guidance, and restore/reset patterns. - dates-and-times: show TimeSpan.Humanize usage with custom separators/toWords and simplify ordinal example API. - enumerations: document UseEnumDescriptionPropertyLocator and recommend startup registration and test restoration. - heading: replace CultureContext with explicit try/finally culture swap, rename Short/FromShortHeading to Abbreviated/FromAbbreviatedHeading. - inflector: prefer Kebaberize in examples and update normalization recommendations. - numbers: clarify ToWords supports whole numbers (int/long) and move fractional guidance to tips. - performance: replace CultureScope sample with explicit try/finally culture switch and add tip to always restore culture. - string-transformations: remove global transformer registry guidance, add RemoveDiacritics implementation and a Slug/ToSlug helper, encourage extension helpers for reuse. - testing: prefer capturing/restoring Configurator values in IDisposable fixtures and update sample tests accordingly; update checklist item for restoring settings. - troubleshooting: update test guidance to capture/restore configuration instead of calling Configurator.Reset(). - v3-namespace-migration: fix README link and remove stray Configurator.Localisation lines. - readme: minor wording tweak (use "40" instead of "forty").

…nd invoke it from workflow

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

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

Copilot

Pull Request Overview

This pull request restructures Humanizer's documentation from Jekyll to DocFX, consolidating the README from a comprehensive feature showcase into a concise landing page, and organizing detailed content into modular guides. The changes include:

Replacing Jekyll-based GitHub Pages with a DocFX documentation site
Condensing the 1,100+ line README to ~100 lines focused on installation and navigation
Creating focused documentation pages for features, operations, localization, and integration
Implementing multi-version documentation build infrastructure with versioning support

Reviewed Changes

Copilot reviewed 34 out of 36 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`readme.md`	Streamlined from feature manual to concise navigation hub
`docs/toc.yml`	New DocFX table of contents defining site structure
`docs/docfx.json`	DocFX configuration for metadata and build settings
`docs/*.md`	New feature guides (testing, performance, troubleshooting, etc.)
`docs/v3-namespace-migration.md`	Removed obsolete configuration examples
`docs/index.md`	Updated landing page linking to reorganized guides
`.github/workflows/docfx-gh-pages.yml`	New GitHub Actions workflow for documentation builds
`.github/workflows/scripts/build-docfx.sh`	Multi-version documentation build script
`.gitignore`	Added DocFX-specific exclusions
Jekyll files (`_config.yml`, `_layouts/`, `assets/css/`)	Removed Jekyll scaffolding

docs/time-unit-symbols.md

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

Copilot · 2025-11-06T03:20:40Z

docs/performance.md

+    foreach (var item in items)
+    {
+        item.DisplayAge = item.Created.Humanize();
+        item.DisplayCount = item.Count.ToQuantity("élément");


[nitpick] ToQuantity expects the base word to be singular (e.g., "élément") and will pluralize it. However, this example doesn't show proper usage since French pluralization requires proper vocabulary setup. The code should demonstrate calling ToQuantity with the correct culture or clarify that the vocabulary must be configured for French.

docs/configuration.md

clairernovotny · 2025-11-06T03:26:06Z

@copilot address the code review comments, including this one:

Inside the release loop the script unconditionally executes docfx metadata and docfx build in every rel/* worktree. Existing release branches were created before this migration and still contain the Jekyll docs layout (no docs/docfx.json, different target frameworks). When such a branch is fetched the commands here will fail and the whole GitHub Pages workflow aborts, preventing documentation from publishing. Consider skipping branches that do not contain DocFX configuration or handling failures per branch so older releases do not block the deployment.

Copilot · 2025-11-06T03:26:14Z

@clairernovotny I've opened a new pull request, #1643, to work on those changes. Once the pull request is ready, I'll request review from you.

…acy release branches (#1643) Co-authored-by: clairernovotny <[email protected]> Co-authored-by: copilot-swe-agent[bot] <[email protected]>

Copilot

Pull Request Overview

Copilot reviewed 34 out of 36 changed files in this pull request and generated 6 comments.

docs/testing.md

docs/application-integration.md

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

docs/string-transformations.md

docs/performance.md

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

Co-authored-by: Copilot <[email protected]>

Copilot

Pull Request Overview

Copilot reviewed 34 out of 36 changed files in this pull request and generated 5 comments.

docs/troubleshooting.md

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

docs/troubleshooting.md

docs/index.md

docs/performance.md

clairernovotny · 2025-11-06T03:41:31Z

@copilot address all of the remaining feedback/comments/suggestions and verify that ToQuantity as well

Copilot · 2025-11-06T03:41:39Z

@clairernovotny I've opened a new pull request, #1644, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: clairernovotny <[email protected]> Co-authored-by: Copilot <[email protected]> Co-authored-by: copilot-swe-agent[bot] <[email protected]>

Copilot · 2025-11-06T03:59:30Z

@clairernovotny I've opened a new pull request, #1645, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: clairernovotny <[email protected]> Co-authored-by: copilot-swe-agent[bot] <[email protected]>

Copilot

Pull Request Overview

Copilot reviewed 33 out of 35 changed files in this pull request and generated 5 comments.

Copilot · 2025-11-06T15:15:21Z

docs/performance.md

+    foreach (var item in items)
+    {
+        item.DisplayAge = item.Created.Humanize();
+        // ToQuantity expects a singular word and handles pluralization automatically


The comment states 'ToQuantity expects a singular word,' but ToQuantity is an extension method on int, not string. The correct usage shown would be item.Count.ToQuantity(\"élément\") where the first parameter is the singular word. Consider clarifying this example to show the correct signature: \"élément\".ToQuantity(item.Count) instead, which matches the typical usage pattern seen throughout the codebase.

Suggested change

// ToQuantity expects a singular word and handles pluralization automatically

// ToQuantity is an extension method on int; pass the singular word as the argument (e.g., item.Count.ToQuantity("élément"))

Copilot · 2025-11-06T15:15:21Z

docs/numbers.md

+
+```csharp
+21.Ordinalize();                              // "21st"
+"car".ToQuantity(2).Ordinalize();            // "2nd cars"


The example \"car\".ToQuantity(2).Ordinalize() is incorrect. ToQuantity returns a string, and Ordinalize is not a string extension method. The correct pattern would be 2.Ordinalize() + \" cars\" or just \"car\".ToQuantity(2) without the Ordinalize call. This example will not compile and should be removed or corrected.

Suggested change

"car".ToQuantity(2).Ordinalize(); // "2nd cars"

2.Ordinalize() + " cars"; // "2nd cars"

Copilot · 2025-11-06T15:15:22Z

docs/pluralization.md

+## Culture-specific behavior
+
+Most languages beyond English require a culture-specific vocabulary. Humanizer ships with many built-in vocabularies—for example, `Humanizer.Core.fr` for French. Ensure you set `CultureInfo.CurrentUICulture` or pass a culture explicitly when working across locales.
+


The example implies that French pluralization is built-in by setting CurrentUICulture, but the preceding section states 'Humanizer ships with many built-in vocabularies—for example, Humanizer.Core.fr for French.' For clarity, explicitly mention that the Humanizer.Core.fr package must be installed for this example to work, as pluralization vocabularies are not culture-aware by default in the base package.

Suggested change

> **Note:** To use French pluralization, you must install the `Humanizer.Core.fr` NuGet package:

> ```

> dotnet add package Humanizer.Core.fr

> ```

Copilot · 2025-11-06T15:15:22Z

docs/collection-humanization.md

+var beverages = new[] { "coffee", "tea", "water" };
+string text = beverages.Humanize();          // "coffee, tea, and water"
+text.ToQuantity(3, ShowQuantityAs.Words);    // "three coffee, tea, and water"


The example text.ToQuantity(3, ShowQuantityAs.Words) produces misleading output. ToQuantity is meant to be called on a singular noun (e.g., \"item\".ToQuantity(3) → "3 items"), not on an already-formatted list. The example output "three coffee, tea, and water" is grammatically incorrect and doesn't demonstrate proper usage. Consider replacing this with a clearer example or removing it entirely.

Suggested change

var beverages = new[] { "coffee", "tea", "water" };

string text = beverages.Humanize(); // "coffee, tea, and water"

text.ToQuantity(3, ShowQuantityAs.Words); // "three coffee, tea, and water"

var beverage = "beverage";

beverage.ToQuantity(3, ShowQuantityAs.Words); // "three beverages"

// Or, to pluralize each item in a collection:

var beverages = new[] { "coffee", "tea", "water" };

var pluralized = beverages.Select(b => b.ToQuantity(3, ShowQuantityAs.Words));

pluralized.Humanize(); // "three coffees, three teas, and three waters"

Copilot · 2025-11-06T15:15:23Z

docs/bytesize.md

+backup.ToString();                    // "10.5 GB"
+backup.ToString("#.## MB");          // "10752 MB"
+backup.Humanize("0.00 TB");          // "0.01 TB"
+backup.ToFullWords();                 // "ten point five gigabytes"


The example suggests that ToFullWords() converts numeric values to words ("ten point five"), but based on the original readme, ToFullWords() converts unit abbreviations to full words (e.g., "GB" → "gigabytes") without converting the numeric portion. The expected output should be "10.5 gigabytes" not "ten point five gigabytes". Correct the example output.

Suggested change

backup.ToFullWords(); // "ten point five gigabytes"

backup.ToFullWords(); // "10.5 gigabytes"

Copilot

Pull Request Overview

Copilot reviewed 39 out of 41 changed files in this pull request and generated 1 comment.

Copilot · 2025-11-07T17:09:33Z

nuget.config

+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+    <add key="DocFX" value="https://docfx.pkgs.visualstudio.com/docfx/_packaging/docs-public-packages/nuget/v3/index.json" />
+  </packageSources>
+  <activePackageSource>
+    <add key="All" value="(Aggregate source)" />
+  </activePackageSource>
+</configuration>


According to the build and validation guidance in the coding guidelines, changes to NuGet.config should never be committed. The guidance explicitly states: "If you need to reference those newly built packages, create or update NuGet.config to use that package output path as a package source--but never commit changes to that file."

This nuget.config file adds a DocFX package source which appears to be related to documentation build requirements. While this may be necessary for DocFX, it violates the stated guideline. Consider:

Adding nuget.config to .gitignore to prevent accidental commits

Documenting the DocFX package source requirement in a README or setup guide instead

Using a different mechanism (like a checked-in template or environment-specific configuration) if DocFX requires this source

Copilot

Pull Request Overview

Copilot reviewed 53 out of 58 changed files in this pull request and generated 5 comments.

Copilot · 2025-11-07T19:02:40Z

docs/enumerations.md

+```csharp
+"Ready to ship".DehumanizeTo<OrderStatus>();         // OrderStatus.ReadyToShip
+"ready_to_ship".DehumanizeTo<OrderStatus>();        // OrderStatus.ReadyToShip
+"Awaiting fulfilment".DehumanizeTo<OrderStatus>();  // OrderStatus.AwaitingFulfillment


Spelling error: "fulfilment" should be "fulfillment" (American English, consistent with the rest of the documentation).

Copilot · 2025-11-07T19:02:41Z

docs/performance.md

+    {
+        item.DisplayAge = item.Created.Humanize();
+        // ToQuantity expects a singular word and handles pluralization automatically
+        item.DisplayCount = item.Count.ToQuantity("élément");


The example shows calling ToQuantity on a string ("élément"), but according to the Humanizer API, ToQuantity is an extension method on strings that takes a number. The correct usage should be "élément".ToQuantity(item.Count) rather than item.Count.ToQuantity("élément").

Copilot · 2025-11-07T19:02:41Z

docs/numbers.md

+
+```csharp
+21.Ordinalize();                              // "21st"
+"car".ToQuantity(2).Ordinalize();            // "2nd cars"


The code example shows calling Ordinalize() on a string returned by ToQuantity, but Ordinalize() is a method on integers, not strings. This example appears to be incorrect. It should be something like 2.Ordinalize() to get "2nd", or the example should be corrected to show valid usage.

Copilot · 2025-11-07T19:02:41Z

docs/enumerations.md

+{
+    PendingPayment,
+
+    [Description("Awaiting fulfilment")]


Spelling error: "fulfilment" should be spelled "fulfillment" (American English spelling). Since the rest of the documentation uses American English conventions, this should be consistent.

Copilot · 2025-11-07T19:02:41Z

docs/enumerations.md

+}
+
+OrderStatus.PendingPayment.Humanize();          // "Pending payment"
+OrderStatus.AwaitingFulfillment.Humanize();     // "Awaiting fulfilment"


Spelling error: "fulfilment" should be "fulfillment" (American English, consistent with the rest of the documentation).

- Add DocFxMarkdownGen configuration for Markdown generation - Update build script to handle API documentation and metadata - Create sidebar for API version navigation - Introduce styles for API version picker - Update README and AGENTS.md with tooling expectations - Remove unused CSS for API pages - Add new configuration for DFMG and API version defaults

scripts/generate-docs.sh

+npm run build
+
+if [[ $SERVE -eq 1 ]]; then
+  echo "[docs] Serving build output at http://localhost:3000"


clairernovotny added 3 commits November 5, 2025 18:46

Docs: extract DocFX multi-version build into scripts/build-docfx.sh a…

9d0b15e

…nd invoke it from workflow

Copilot AI review requested due to automatic review settings November 6, 2025 03:17

chatgpt-codex-connector bot reviewed Nov 6, 2025

View reviewed changes

.github/workflows/scripts/build-docfx.sh Outdated Show resolved Hide resolved

Copilot AI reviewed Nov 6, 2025

View reviewed changes

Merge branch 'main' into use-docfx

402b28b

Copilot AI mentioned this pull request Nov 6, 2025

Address code review feedback: fix documentation syntax and handle legacy release branches #1643

Merged

Address code review feedback: fix documentation syntax and handle leg…

ca4b984

…acy release branches (#1643) Co-authored-by: clairernovotny <[email protected]> Co-authored-by: copilot-swe-agent[bot] <[email protected]>

Copilot AI review requested due to automatic review settings November 6, 2025 03:33

Copilot AI reviewed Nov 6, 2025

View reviewed changes

Update docs/application-integration.md

5d312f0

Co-authored-by: Copilot <[email protected]>

Copilot AI review requested due to automatic review settings November 6, 2025 03:37

Update docs/string-transformations.md

b8fdf57

Co-authored-by: Copilot <[email protected]>

Copilot AI reviewed Nov 6, 2025

View reviewed changes

docs/troubleshooting.md Show resolved Hide resolved

.github/workflows/scripts/build-docfx.sh Outdated Show resolved Hide resolved

docs/troubleshooting.md Outdated Show resolved Hide resolved

docs/index.md Outdated Show resolved Hide resolved

docs/performance.md Show resolved Hide resolved

Copilot AI mentioned this pull request Nov 6, 2025

Fix documentation paths, error codes, and script robustness #1644

Merged

Fix documentation paths, error codes, and script robustness (#1644)

4e8df74

Co-authored-by: clairernovotny <[email protected]> Co-authored-by: Copilot <[email protected]> Co-authored-by: copilot-swe-agent[bot] <[email protected]>

Copilot AI mentioned this pull request Nov 6, 2025

Automate API toc.yml generation in DocFX #1645

Merged

Automate API toc.yml generation in DocFX (#1645)

f05cc09

Co-authored-by: clairernovotny <[email protected]> Co-authored-by: copilot-swe-agent[bot] <[email protected]>

Copilot AI review requested due to automatic review settings November 6, 2025 15:12

Copilot AI reviewed Nov 6, 2025

View reviewed changes

clairernovotny added 2 commits November 7, 2025 10:35

fixes

ff6efd6

add docfx prerelease feed

2aae79f

Copilot AI review requested due to automatic review settings November 7, 2025 17:07

Copilot AI reviewed Nov 7, 2025

View reviewed changes

clairernovotny added 3 commits November 7, 2025 12:20

remove old feed

47746b8

Adopt Docusaurus shell with DocFX API pipeline

18cb468

add serena config

7a4db65

Copilot AI review requested due to automatic review settings November 7, 2025 19:00

Copilot AI reviewed Nov 7, 2025

View reviewed changes

clairernovotny added 6 commits November 7, 2025 14:30

Add docs generation helper script

37257ee

Improve API docs navigation and theming

7341a4e

Enable Prism syntax highlighting for docs

de24982

Fix API page layout and hook usage

99505c3

Refactor build commands in suggested_commands.md for clarity

4fab166

github-advanced-security bot found potential problems Nov 10, 2025

View reviewed changes

scripts/generate-docs.sh

npm run build

if [[ $SERVE -eq 1 ]]; then

echo "[docs] Serving build output at http://localhost:3000"

Check notice

Code scanning / devskim

Accessing localhost could indicate debug code, or could hinder scaling. Note

Do not leave debug code in production

	// ToQuantity expects a singular word and handles pluralization automatically
	// ToQuantity is an extension method on int; pass the singular word as the argument (e.g., item.Count.ToQuantity("élément"))

	"car".ToQuantity(2).Ordinalize(); // "2nd cars"
	2.Ordinalize() + " cars"; // "2nd cars"

		## Culture-specific behavior

		Most languages beyond English require a culture-specific vocabulary. Humanizer ships with many built-in vocabularies—for example, `Humanizer.Core.fr` for French. Ensure you set `CultureInfo.CurrentUICulture` or pass a culture explicitly when working across locales.

+> **Note:** To use French pluralization, you must install the `Humanizer.Core.fr` NuGet package:
+> ```
+> dotnet add package Humanizer.Core.fr
+> ```

-var beverages = new[] { "coffee", "tea", "water" };
-string text = beverages.Humanize();          // "coffee, tea, and water"
-text.ToQuantity(3, ShowQuantityAs.Words);    // "three coffee, tea, and water"
+var beverage = "beverage";
+beverage.ToQuantity(3, ShowQuantityAs.Words);    // "three beverages"
+// Or, to pluralize each item in a collection:
+var beverages = new[] { "coffee", "tea", "water" };
+var pluralized = beverages.Select(b => b.ToQuantity(3, ShowQuantityAs.Words));
+pluralized.Humanize(); // "three coffees, three teas, and three waters"

	backup.ToFullWords(); // "ten point five gigabytes"
	backup.ToFullWords(); // "10.5 gigabytes"

Migrate docs site from Jekyll to DocFX #1642

Are you sure you want to change the base?

Migrate docs site from Jekyll to DocFX #1642

Conversation

clairernovotny commented Nov 6, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

clairernovotny commented Nov 6, 2025

Uh oh!

Copilot AI commented Nov 6, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clairernovotny commented Nov 6, 2025

Uh oh!

Copilot AI commented Nov 6, 2025

Uh oh!

Copilot AI commented Nov 6, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment