docs: redesign the Humanizer documentation experience - #1891
Conversation
|
Warning Review limit reached
Next review available in: 5 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR adds design and product documentation, aligns site content and generated metadata with Humanizer 4, simplifies supported-culture documentation, redesigns the homepage, and updates browser and version-routing tests. ChangesHumanizer 4 documentation alignment
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Browser
participant Homepage
participant Documentation
Browser->>Homepage: Load redesigned homepage
Homepage->>Documentation: Provide guide, culture, and API links
Browser->>Documentation: Navigate to selected documentation route
Possibly related PRs
Suggested labels: Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 390207cce8
ℹ️ 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".
There was a problem hiding this comment.
Pull request overview
Redesigns the Humanizer documentation experience to be task-first and version-explicit, including a new homepage “proof sheet” layout, updated version labeling for the next major release line, and a simplified supported-culture presentation backed by accessibility and E2E tests.
Changes:
- Rebuild the homepage into a first-viewport proof sheet with runnable input→output examples, install guidance, and task-based navigation.
- Rename “main/preview” references throughout the docs/test suite to an explicit “Humanizer 4 / 4.0 (next)” framing and update upgrade/installation guidance accordingly.
- Replace the locale capability matrix with an all-or-nothing supported-culture list and add product/design system documentation to preserve constraints and accessibility goals.
Reviewed changes
Copilot reviewed 42 out of 42 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| website/tests/versionRoutes.test.mjs | Updates expected version labels/routes for the new “4.0 (next)” naming. |
| website/tests/e2e/reader-shell.spec.ts | Aligns E2E assertions with new homepage content, nav labels, and version dropdown. |
| website/tests/e2e/production.spec.ts | Updates production smoke expectations for the new homepage heading. |
| website/tests/e2e/accessibility.spec.ts | Updates accessibility coverage to target the supported-culture list instead of a table region. |
| website/src/pages/index.tsx | Replaces homepage layout with proof-sheet table, install snippet, task routes, and language promise. |
| website/src/pages/index.module.css | Implements new homepage visual system (grid, proof sheet, task list, promise band). |
| website/src/css/custom.css | Adds supported-culture list styling. |
| website/humanizer-versions.json | Renames current docs label to “4.0 (next)” while keeping route /docs/next. |
| website/docs/upgrading/version-3-migration.mdx | Updates text to refer to “Humanizer 4” as the future boundary. |
| website/docs/upgrading/main-preview.mdx | Reframes “main/preview” doc as “Upgrade from 3.0.10 to Humanizer 4” with updated steps. |
| website/docs/upgrading/index.mdx | Updates upgrade chooser copy/links to point at the Humanizer 4 upgrade guide. |
| website/docs/start/troubleshooting.mdx | Updates troubleshooting guidance around culture support and versioned docs behavior. |
| website/docs/start/quick-start.mdx | Updates quick start text/commands for Humanizer 4 framing. |
| website/docs/start/package-selection.md | Updates package selection matrix and example install command for Humanizer 4 framing. |
| website/docs/start/overview.mdx | Updates overview narrative about versioned snapshots and next-version docs. |
| website/docs/start/installation.mdx | Updates installation guidance and version notes for Humanizer 4 framing. |
| website/docs/scenarios/strings-and-casing.mdx | Renames “main/preview” behavior notes to “Humanizer 4”. |
| website/docs/scenarios/numbers-words-ordinals-roman-bytes-and-quantities.mdx | Updates version notes to reference Humanizer 4 boundaries. |
| website/docs/scenarios/localization-and-extensibility.mdx | Updates version notes and API availability wording for Humanizer 4. |
| website/docs/scenarios/inflection-and-quantities.mdx | Updates pluralization/acronym and v4 behavior notes to “Humanizer 4”. |
| website/docs/scenarios/index.mdx | Updates scenario index version coverage statement to include Humanizer 4. |
| website/docs/scenarios/enums-and-flags.mdx | Updates enum/dehumanize and overload availability notes to “Humanizer 4”. |
| website/docs/scenarios/durations-and-ages.mdx | Updates duration API availability notes to “Humanizer 4”. |
| website/docs/scenarios/byte-sizes-and-rates.mdx | Updates ByteSize/ByteRate version notes to “Humanizer 4”. |
| website/docs/languages/using-cultures.mdx | Updates culture support guidance and API notes to “Humanizer 4”. |
| website/docs/languages/supported-cultures.mdx | Replaces capability matrix with supported-culture list and all-or-nothing support contract wording. |
| website/docs/languages/language-coverage.json | Updates generated-for metadata from “main/preview” to “4.0”. |
| website/docs/languages/index.mdx | Updates languages landing page guidance to match supported-culture list + v4 framing. |
| website/docs/languages/grammar-and-platform-formatting.mdx | Updates HumanizeWithCase wording to “Humanizer 4”. |
| website/docs/languages/custom-localization.mdx | Updates registry freezing and customization notes to “Humanizer 4”. |
| website/docs/index.md | Updates root docs index links/labels for supported cultures and Humanizer 4 upgrade guide. |
| website/docs/contributing/report-language-issue.mdx | Updates link text to “Supported cultures”. |
| website/docs/contributing/index.mdx | Updates link text to “Supported cultures”. |
| website/docs/concepts/trimming-and-native-aot.mdx | Updates AOT verification and API availability notes to “Humanizer 4”. |
| website/docs/concepts/culture-and-configuration.mdx | Refines fallback description for unsupported cultures. |
| website/docs/api/index.md | Updates API provenance wording to Humanizer 4 reference assembly. |
| website/docs/analyzer/index.mdx | Updates analyzer docs to refer to Humanizer 4 (not “current preview”). |
| tools/docs/snapshot.ps1 | Updates generated API landing provenance string for current docs. |
| tools/docs/generate-language-coverage.ps1 | Updates generated-for marker to “4.0”. |
| PRODUCT.md | Adds product constraints/contract documentation for the docs experience. |
| DESIGN.md | Adds a design system spec (tokens, layout, accessibility constraints). |
| .impeccable/design.json | Adds structured design-system metadata for automated checks/tooling. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/docs/start/overview.mdx`:
- Around line 39-44: Update the Humanizer 4 release-status wording in the
overview documentation to reflect that version 4 is released, removing the
“upcoming” description while preserving the existing coverage and maintenance
caveats.
In `@website/docs/start/quick-start.mdx`:
- Around line 20-25: Do not present Humanizer 4.0.0 as a published NuGet
release: update website/docs/start/quick-start.mdx (20-25),
website/docs/languages/language-coverage.json (5),
website/docs/languages/using-cultures.mdx (60, 80-87),
website/docs/start/troubleshooting.mdx (64), website/docs/index.md (37-44),
website/docs/scenarios/byte-sizes-and-rates.mdx (29, 60, 90, 112),
website/docs/upgrading/index.mdx (86-87, 121),
website/docs/upgrading/main-preview.mdx (3-75, 84-101), and
website/docs/upgrading/version-3-migration.mdx (47) to restore preview
qualifiers or provide preview/local-feed instructions; alternatively gate these
references until package 4.0.0 is published.
In `@website/src/pages/index.module.css`:
- Around line 2-3: Fix the Stylelint violations in the CSS declarations around
the custom property and the additionally referenced ranges: add required
declaration separation, remove deprecated clip usage, and normalize currentcolor
to Stylelint’s canonical lowercase casing. Preserve the existing styling while
ensuring the enforced formatting and validation checks pass.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 0666ee50-fd0b-4b6a-a5ef-3f84118f77c2
📒 Files selected for processing (42)
.impeccable/design.jsonDESIGN.mdPRODUCT.mdtools/docs/generate-language-coverage.ps1tools/docs/snapshot.ps1website/docs/analyzer/index.mdxwebsite/docs/api/index.mdwebsite/docs/concepts/culture-and-configuration.mdxwebsite/docs/concepts/trimming-and-native-aot.mdxwebsite/docs/contributing/index.mdxwebsite/docs/contributing/report-language-issue.mdxwebsite/docs/index.mdwebsite/docs/languages/custom-localization.mdxwebsite/docs/languages/grammar-and-platform-formatting.mdxwebsite/docs/languages/index.mdxwebsite/docs/languages/language-coverage.jsonwebsite/docs/languages/supported-cultures.mdxwebsite/docs/languages/using-cultures.mdxwebsite/docs/scenarios/byte-sizes-and-rates.mdxwebsite/docs/scenarios/durations-and-ages.mdxwebsite/docs/scenarios/enums-and-flags.mdxwebsite/docs/scenarios/index.mdxwebsite/docs/scenarios/inflection-and-quantities.mdxwebsite/docs/scenarios/localization-and-extensibility.mdxwebsite/docs/scenarios/numbers-words-ordinals-roman-bytes-and-quantities.mdxwebsite/docs/scenarios/strings-and-casing.mdxwebsite/docs/start/installation.mdxwebsite/docs/start/overview.mdxwebsite/docs/start/package-selection.mdwebsite/docs/start/quick-start.mdxwebsite/docs/start/troubleshooting.mdxwebsite/docs/upgrading/index.mdxwebsite/docs/upgrading/main-preview.mdxwebsite/docs/upgrading/version-3-migration.mdxwebsite/humanizer-versions.jsonwebsite/src/css/custom.csswebsite/src/pages/index.module.csswebsite/src/pages/index.tsxwebsite/tests/e2e/accessibility.spec.tswebsite/tests/e2e/production.spec.tswebsite/tests/e2e/reader-shell.spec.tswebsite/tests/versionRoutes.test.mjs
|
@codex review |
|
@codex review |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 42 out of 42 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (4)
website/docs/upgrading/main-preview.mdx:25
- This upgrade guide pins
--version 4.0.0, but the repository versioning is4.0.0-preview.*(version.json:2) and the docs manifest marks the "4.0 (next)" docs as generated frommainwithpublished: false(website/humanizer-versions.json:175-191). If this page is meant for the next/preview line, use a prerelease install instruction to avoid pointing readers at a likely-nonexistent stable version.
website/docs/start/installation.mdx:23 - This pins a stable
--version 4.0.0, but the repository versioning is4.0.0-preview.*(version.json:2) and the docs manifest marks the "4.0 (next)" docs as generated from themaincheckout withpublished: false(website/humanizer-versions.json:175-191). Using a prerelease install command keeps the docs aligned with the preview/unpublished line.
dotnet add package Humanizer --version 4.0.0
website/docs/start/quick-start.mdx:25
- This pins
--version 4.0.0, but the repository version scheme is4.0.0-preview.*(version.json:2) and the docs manifest identifies the current docs as "4.0 (next)" and not published (website/humanizer-versions.json:175-191). A prerelease install command is more consistent with the preview/unpublished state.
dotnet add package Humanizer --version 4.0.0
website/docs/start/package-selection.md:30
- This command pins
--version 4.0.0, but the repo versioning is4.0.0-preview.*(version.json:2) and the current docs version is "4.0 (next)" withpublished: false(website/humanizer-versions.json:175-191). If this page targets the next/preview line, prefer a prerelease install so the command doesn't fail or select the wrong release line.
dotnet add package Humanizer --version 4.0.0
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5cb24764e1
ℹ️ 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".
|
@codex review |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 42 out of 42 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
.impeccable/design.json:82
- The design system records
scroll-behavior: smoothas a global motion effect, but the design docs also require reduced-motion support. Smooth scrolling should be disabled underprefers-reduced-motion: reduceto avoid forcing motion for users who opt out.
],
"effects": {
"shadow": "0 1px 0 var(--ifm-color-emphasis-300)",
"motion": "scroll-behavior: smooth"
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 329eccad75
ℹ️ 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".
|
✅ Action performedReview finished.
|
|
@codex review @coderabbitai review |
|
✅ Action performedReview finished.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fb2f300c1a
ℹ️ 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".
|
@codex review @coderabbitai review |
|
✅ Action performedReview finished.
|
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 42 out of 42 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
website/src/pages/index.tsx:157
- This homepage link hardcodes the preview docs route (/docs/next/...) while the rest of the homepage links target the latest-stable docs (/docs/...). With Docusaurus configured to serve the latest stable at /docs/ and the preview at /docs/next/, this breaks the "version-correct" navigation promise and ignores the user's selected/preferred docs version.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b169fc3b6e
ℹ️ 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".
|
@codex review @coderabbitai review |
|
✅ Action performedReview finished.
|
|
Codex Review: Didn't find any major issues. Delightful! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 42 out of 42 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (4)
website/docs/start/quick-start.mdx:25
- This quick-start installs
Humanizer --version 4.0.0, but the repository version metadata indicates4.0.0-preview.*builds. If 4.0.0 isn’t published as a stable package yet, readers won’t be able to run this command as written.
dotnet add package Humanizer --version 4.0.0
website/docs/start/package-selection.md:30
- This example pins
Humanizer --version 4.0.0, but the repository version metadata indicates the current line is4.0.0-preview.*. If 4.0.0 hasn’t been released as a stable NuGet package yet, this command won’t work as written.
dotnet add package Humanizer --version 4.0.0
website/docs/upgrading/main-preview.mdx:25
- This example pins
Humanizer --version 4.0.0, but the repository version metadata is4.0.0-preview.*(version.json). If 4.0.0 is not published as a stable NuGet package yet, this command will fail for readers; consider using a prerelease-friendly command or otherwise aligning the docs with the published package version.
website/docs/start/installation.mdx:23 - This installs
Humanizer --version 4.0.0, but the repository version metadata indicates the current line is4.0.0-preview.*. If a stable 4.0.0 package is not published yet, this command will fail.
dotnet add package Humanizer --version 4.0.0
Summary
Why
Developers should be able to understand Humanizer, install the correct package,
and reach the relevant task guide from the first viewport. The documentation
should describe released package usage rather than source-build installation,
and locale support should reflect the repository's all-or-nothing quality
contract instead of implying tiers of incomplete behavior.
Validation
pnpm typecheckpnpm test:unit— 45 passedpnpm check:contentpnpm buildpnpm test:ci— 39 passed across desktop/mobile and light/dark modespnpm check:artifactpnpm check:linkspnpm check:search-budget— all eight version indexes and exact routes passedpwsh -NoProfile -File tools/docs/test.ps1 -ReleaseVersion 3.0.8—published-package culture data, trimmed/Native AOT examples, snapshot
immutability, rollback, and failure checks passed
Production smoke remains deployment-only and will run in the documentation
deployment workflow.
Checklist
mainAGENTS.mdis greenNo issue is closed by this independent documentation redesign.