docs: establish v4 onboarding contract - #1895
Conversation
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe PR updates documentation validation rules and tests, refreshes Humanizer 4 landing and start-guide content, removes package selection from the sidebar, and revises configuration and troubleshooting guidance. ChangesDocumentation validation and guide refresh
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested labels: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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 |
There was a problem hiding this comment.
Pull request overview
Updates the Humanizer website onboarding docs to assume Humanizer 4 as the primary entry point, and relaxes the content-gate “template section” requirements while still enforcing meaningful frontmatter and tutorial expectations.
Changes:
- Simplifies “Start” documentation pages to a v4-first, output-forward onboarding flow (install → quick start → configuration → troubleshooting).
- Updates the content verification contract to require
titlefrontmatter and to make template sections optional, while still enforcing example/result requirements for tutorials. - Adjusts unit tests and navigation to reflect the updated content contract and onboarding structure.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| website/tests/contentCheck.test.mjs | Updates content-check unit tests to cover the new “concise page” contract, required title, and tutorial requirements. |
| website/sidebars.json | Removes the package-selection page from the Start sidebar navigation. |
| website/docs/start/troubleshooting.mdx | Rewrites troubleshooting to be v4-first with a minimal reproduction and clearer symptom/action guidance. |
| website/docs/start/quick-start.mdx | Renames and refocuses the quick start as a developer-oriented tutorial with deterministic output emphasis. |
| website/docs/start/package-selection.md | Replaces detailed package layout guidance with a v4 “one package” message, keeping the page for inbound links. |
| website/docs/start/overview.mdx | Streamlines overview to show a concrete output and provides clearer next-step paths. |
| website/docs/start/installation.mdx | Simplifies installation guidance for the single v4 package and clarifies supported TFMs. |
| website/docs/start/configuration.mdx | Reframes configuration guidance around startup strategies and highlights the observed output. |
| website/docs/index.md | Updates the docs landing page to describe v4 scope and refreshes key entry links. |
| tools/docs/verify-content.mjs | Updates the content gate to require title and to stop enforcing boilerplate sections on every page, while keeping tutorial/example constraints. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![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: 5099ac0dd9
ℹ️ 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".
![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
🧹 Nitpick comments (1)
website/docs/start/troubleshooting.mdx (1)
46-46: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMake the platform-difference investigation actionable.
“Humanizer's generated platform-formatting coverage” has no linked artifact, command, or location, so users cannot perform the prescribed check. Link the coverage source if it exists; otherwise replace it with a concrete reproducible comparison step.
🤖 Prompt for 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. In `@website/docs/start/troubleshooting.mdx` at line 46, Update the troubleshooting table entry for platform-specific output differences to make the Humanizer formatting check actionable: link to the generated platform-formatting coverage source when available, or replace that phrase with a concrete reproducible comparison command or procedure. Preserve the guidance about comparing .NET globalization data and avoiding assertions on platform-owned text without an explicit override.
🤖 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 `@tools/docs/verify-content.mjs`:
- Around line 105-113: Update the hasExampleSection check in the content
validation logic to recognize Markdown headings with permitted whitespace
between the ## marker and Example, and before the line ending. Extend the
related fixture tests to cover headings such as “## Example” and “## Example ”
while preserving rejection of unrelated headings.
- Around line 98-100: Update the title validation in the content verification
flow around the metadata.title check to reject empty or whitespace-only strings,
including values parsed from either single- or double-quoted titles. Normalize
the title before validating it, preserve the existing missing-title failure
behavior, and add a regression fixture covering an empty quoted title.
In `@website/docs/start/troubleshooting.mdx`:
- Around line 36-37: Update the troubleshooting instruction around the dotnet
package check to scope it explicitly to the application project, either by
running the command from that project’s directory or by supplying its .csproj
path; retain the --include-transitive option and Humanizer 4 verification.
---
Nitpick comments:
In `@website/docs/start/troubleshooting.mdx`:
- Line 46: Update the troubleshooting table entry for platform-specific output
differences to make the Humanizer formatting check actionable: link to the
generated platform-formatting coverage source when available, or replace that
phrase with a concrete reproducible comparison command or procedure. Preserve
the guidance about comparing .NET globalization data and avoiding assertions on
platform-owned text without an explicit override.
🪄 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: 62af97b0-5564-4583-87ba-4715d8678cf9
📒 Files selected for processing (10)
tools/docs/verify-content.mjswebsite/docs/index.mdwebsite/docs/start/configuration.mdxwebsite/docs/start/installation.mdxwebsite/docs/start/overview.mdxwebsite/docs/start/package-selection.mdwebsite/docs/start/quick-start.mdxwebsite/docs/start/troubleshooting.mdxwebsite/sidebars.jsonwebsite/tests/contentCheck.test.mjs
💤 Files with no reviewable changes (1)
- website/sidebars.json
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 779fde2b93
ℹ️ 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
Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (2)
website/tests/contentCheck.test.mjs:33
validPageis no longer a “valid” fixture: it intentionally fails the checker unlessexample: illustrativeis added. Renaming it (e.g.,unlabeledIllustrativePage/illustrativePageTemplate) would make the test intent clearer and reduce future confusion when adding new cases.
const validPage = `---
title: Configure a task
diataxis: how-to
persona: existing user
---
## Example
This fragment is illustrative:
\`\`\`csharp
Console.WriteLine("illustrative");
\`\`\`
`;
tools/docs/verify-content.mjs:100
- The
missing titlecheck can be bypassed with inline YAML comments (e.g.,title: "" # commentortitle: " " # comment). Docusaurus/YAML will treat that as an empty/whitespace title, but the current regex won’t match because of the trailing comment text.
if (!metadata.title || /^(['"])\s*\1$/.test(metadata.title)) {
failures.push(`${relativePage}: missing title`);
}
|
Addressed the review-body findings in
The checker now rejects empty and whitespace-only single- or double-quoted titles, with regressions for all three forms.
The exact heading matcher now accepts Markdown horizontal whitespace while preserving the runnable/illustrative requirement.
The command is now explicitly run from the application project directory, and the platform row gives a same-input/same-culture OS/TFM comparison procedure plus the platform-formatting guide. Validated with |
Summary
Current documentation now onboards developers directly into Humanizer 4: one package, a compact developer quick start, visible outputs, and v4-specific configuration/troubleshooting guidance. The content gate now enforces meaningful frontmatter and page-type requirements without forcing every page to carry Orientation, Pitfall, Version notes, or other boilerplate sections.
This provides the content contract used by the separately reviewable scenario, reference, contributor, and v4 release-guide PRs.
Validation
pnpm --dir website run test:unit— 50/50 passed, including anchored Example-heading coverage.pnpm --dir website run check:content— all seven areas passed.pnpm --dir website run typecheck— passed.git diff --check— passed.Checklist
mainas an independent documentation foundation.