docs: fix where troubleshooting is filed, and stop arguing before the install command - #8
Conversation
The nav had three groups, and the third was "About": migration, troubleshooting and the changelog. None of those is about the project. Troubleshooting is the one that mattered. It is the page you want when a check has just failed, and nobody looks under "About" for that — it had exactly one inbound link in the whole site, buried in a collapsed admonition, so the nav was doing nearly all the work of making it findable and the nav had it filed wrong. Two groups now, split by what the reader is doing rather than what the page is: Guides are followed to get something done, Reference is looked a fact up in. Troubleshooting and migration join the guides, the changelog joins the reference, and "About" is gone. Section names are not URLs, so nothing needs a redirect. Also link troubleshooting from "Where to go next" on the getting started page — the first failure tends to arrive shortly after the first success — and fix a link that still called the migration page by its old title. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
The landing page made its case three times before telling anyone what to run. "Why it exists" (279 words) was followed immediately by four cards restating it, then six more cards, then two more sections — thirteen cards across three grids, with `pip install` at line 350. Two of those four cards were the prose again in shorter form. "One config" is already the heading of the section above it and the closing line of the prose; "Stable rule IDs" is that same closing line's second half. The grid is gone, and the two points that were not duplicates are kept where they land better: enforcement being cheapest in the hook joins the paragraph it elaborates, and SLSA provenance moves next to the install command, which is where "can I trust this package" comes up. The install block now sits directly after the tabs, so a reader who arrived already convinced gets the command at 876px instead of 3000, and one who needs convincing still has the prose immediately below it. Its heading claimed two minutes while the page its own button links to says five. Neither number was doing any work, and the section shows two commands, so it says that instead. Nine cards in two grids, down from thirteen in three. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
✅ Deploy Preview for commit-check ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Warning Review limit reached
Next review available in: 42 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. 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. 📝 WalkthroughWalkthroughThe documentation adds a prominent quick-start section, clarifies local and CI enforcement, exposes troubleshooting guidance, reorganizes navigation, and updates the v2.0.0 migration link text. ChangesDocumentation updates
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@docs/index.md`:
- Around line 73-76: Update the shell example in the documentation near the
commit-check commands to use an indented code block instead of fenced syntax,
and remove the leading `$` prompt characters because no command output is shown.
Preserve both commands unchanged otherwise.
- Around line 102-105: Align the CI workflow and pre-commit hook examples by
enabling the author-email check in the GitHub Actions configuration with the
existing commit-check action settings, or revise the equivalence statement and
hook example to cover only the shared message and branch checks.
🪄 Autofix
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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: dad810c1-7780-47c7-994c-42b971cd7ed0
📒 Files selected for processing (4)
docs/changelog.mddocs/getting-started.mddocs/index.mdmkdocs.yml
| ```console | ||
| $ pip install commit-check | ||
| $ commit-check --message --branch | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the shell block style before merging.
markdownlint-cli2 reports MD046 because the block is fenced and MD014 because the $ commands show no output. Use an indented block without prompt characters when no output is shown.
Proposed fix
-```console
-$ pip install commit-check
-$ commit-check --message --branch
-```
+ pip install commit-check
+ commit-check --message --branch📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```console | |
| $ pip install commit-check | |
| $ commit-check --message --branch | |
| ``` | |
| pip install commit-check | |
| commit-check --message --branch |
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 73-73: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 74-74: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 75-75: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 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 `@docs/index.md` around lines 73 - 76, Update the shell example in the
documentation near the commit-check commands to use an indented code block
instead of fenced syntax, and remove the leading `$` prompt characters because
no command output is shown. Preserve both commands unchanged otherwise.
Source: Linters/SAST tools
The section is headed "One config, enforced everywhere" and says the same rules run on a laptop and in CI. The tabs under it showed three different check sets: the CLI ran message and branch, pre-commit added check-author-email, and the Action ran message and branch — where author-email defaults to false in action.yml, so it was not running there at all. The illustration contradicted the sentence it illustrates. Dropping the author-email hook makes all three exactly message plus branch, which is the parallel the section is claiming. The full hook list already lives in the integrations guide, where it is the subject rather than an aside. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
|
One of the two was real and is fixed in 7db24ef. Fixed: the tabs disagreed with the sentence above them. Correct, and worse than reported — it was three sets, not two. Under a heading reading "One config, enforced everywhere", the CLI tab ran Confirmed against
So Not changing: MD046/MD014 on the install block. Both are markdownlint defaults that this stack has already answered. MD014 exists because a <span class="gp">$ </span>pipThe MD046 wants indented blocks. Switching would cost the syntax highlighting and the copy button, both of which come from the fence and its Generated by Claude Code |
…rt off The section justifies the tool with four concrete costs. Checking each against the rule it depends on turned up two problems. The bisect example gave the right conclusion for the wrong reason. Merge commits recording "nothing but a sync" is a complaint about noise, and noise is a `git log` problem. What merges actually do to a bisect is make the result ambiguous: the run ends on a merge, and the change that broke the build could be in either parent or in the resolution. That is also the reason someone would forbid them, so the example now says it. The signoff example said a contribution "has to be rejected" months later. That is not what happens — a missing trailer is remediated by rewriting the branch with `--signoff`. The sting is the same and this version is true, which matters in a paragraph whose whole force comes from the examples being real. Then the gap worth closing: of those four costs, only the first is prevented by a default install. Merge commits are permitted unless you forbid them and signoff is not required unless you require it, so a reader following the install command directly above this section would still hit two of the four. Rather than swap the examples for tamer ones that happen to be on, name the split — those two are decisions rather than defects, and a tool that made them for you would be overreaching. That also sets up "What it is not" further down the page. Splitting the closing paragraph in passing: the enforcement-is-cheap point and the linter analogy were one 62-word run. Reordering rather than just splitting them keeps the analogy last, where it reads as a close instead of needing an "And" to bolt it on. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
2 participants
What
Two findings from a structural review of the site, taken in the order agreed: navigation first, then the landing page.
Troubleshooting was filed where nobody would look
The nav had three groups, and the third was
About: migration, troubleshooting and the changelog. None of those is about the project.Troubleshooting is the one that mattered. It is the page you want when a check has just failed — and it had exactly one inbound link in the whole site, buried in a collapsed admonition in the pre-commit guide. So the nav was doing nearly all the work of making it findable, and the nav had it under "About".
Two groups now, split by what the reader is doing rather than what the page is:
Aboutis gone. Section names are not URLs, so no page moved and nothing needs a redirect — verified all ten pages still build to their existing paths, sitemap unchanged at 19 entries.Troubleshooting is also now linked from "Where to go next" on the getting started page, since the first failure tends to arrive shortly after the first success. And a link that still called the migration page by its pre-rewrite title is fixed.
The landing page argued its case three times before saying what to run
Why it exists(279 words) was followed immediately by four cards restating it, then six more cards, then two more sections. Thirteen cards across three grids, withpip installat line 350.Measured before and after, in Chromium at 1280px:
The four cards were checked one at a time rather than cut wholesale:
The install block now sits directly after the tabs. A reader who arrived already convinced gets the command without scrolling past four sections of argument; one who needs convincing still has the prose immediately below it.
Its heading also claimed "two minutes" while the page its own button links to says "about five minutes". Neither number was doing any work and the section shows two commands, so it says that instead. Confirmed nothing links to the renamed anchor.
Test plan
mkdocs build --strictclean; 8 tests passAboutabsent from the rendered navNote
The proxy here blocks external hosts, so I could not open the deploy preview — everything above was measured against a local build. Worth a look at the preview before merging, particularly the landing page flow.
Not included, still open from the review: the "Trusted by" wording (needs your judgement on actual usage), the community section's two buttons, the blog index, and a
--compactoutput inconsistency that belongs upstream incommit-checkrather than here.Generated by Claude Code
Summary by CodeRabbit