docs: consolidate the site from 17 pages to 10 - #4
Merged
Conversation
The previous commit listed #462 and #464 under v2.12.0, but both shipped in v2.11.1 — a release the changelog still had no section for at all. Moves the bullet to a new v2.11.1 section, which also closes the last gap between v2.11.0 and today. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
The site had pre-commit.com's content volume spread across nearly twice the navigation destinations: nine pages under 100 lines, and four places where the same material was written twice — install steps in both installation.md and quickstart step 1, CLI invocations in both quickstart and example.md, releases in both what-is-new.md and changelog.md, and "what it checks" on the landing page restating the rules reference. Merges installation and quickstart into one Getting started page; the three deployment guides into Integrations; the two opt-in policy guides into Policy guides; why.md and projects.md into the landing page. what-is-new.md becomes a Highlights table at the top of the changelog that links into the entries below rather than restating them, so a release is written up once. rules.md and configuration.md do not move. Every released version of the package prints commit-check.com/rules/#ccNNN, hardcoded in rules_catalog.py, so that URL is a published interface rather than a documentation path. Every retired URL gets a redirect stub from the build hook — production is GitHub Pages, where netlify.toml has no effect — and the forced /getting-started/ redirect is gone now that a real page lives there. Also fixes what the merge surfaced: the GitHub Actions guide pinned commit-check-action@v1 when the action has been on v2 since v2.0.0, the changelog named the author options author_name/author_email rather than author_name_pattern/author_email_pattern, and the pre-commit rev was two minor versions behind. Version badges are dropped from the ecosystem cards; they went stale on their own. The pages cross-link by section anchor now, and a stale anchor is invisible in a rendered page — it just scrolls to the top. mkdocs validation for anchors and unrecognized links is turned on, so --strict fails the deploy build instead. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
v2.13.0 shipped on 2026-08-04, so the changelog date that was a placeholder is now the real one and needs no change. The five pre-commit `rev:` pins across the guides, the landing page, the recipes and the configuration reference were spread over four different versions, none of them current. The blog post keeps its own pin — a dated post records what was true when it was written. Adds #514 to the v2.13.0 documentation entry, which the release notes list alongside the other three domain-move PRs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
The docs-sync job installed commit-check from main because the rule IDs this site documents were merged but unreleased, and PyPI would have reported a mismatch that was not real. v2.13.0 is on PyPI now, so that exception has expired — and while it stood, the job was validating the site against code no reader could install. Left unpinned on purpose: the check is meaningful only against the version a reader gets from `pip install commit-check`, and a pin would let the site and the package drift until somebody remembered to raise it. Verified against the released 2.13.0 rather than the working tree — all seven checks pass, so the rule names, headings and documented defaults on the site match the package as shipped. 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. |
📝 WalkthroughWalkthroughThis PR restructures documentation by consolidating pre-commit, GitHub Actions, organization-config, signoff, and AI-attribution guides into new Integrations and Policy guides, deletes several standalone pages, updates changelog anchors, refreshes cross-page links and version pins, adjusts mkdocs navigation/validation, and updates Netlify and mkdocs-hook redirects. The deploy workflow now installs commit-check from PyPI instead of the main branch. ChangesDocumentation consolidation and site routing
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant Developer
participant GitHubActions as GitHub Actions
participant SharedConfig as Shared cchk.toml
participant CommitCheck as commit-check CLI
Developer->>GitHubActions: push or pull_request
GitHubActions->>SharedConfig: fetch inherited configuration
SharedConfig-->>GitHubActions: merged configuration
GitHubActions->>CommitCheck: run checks with merged config
CommitCheck-->>GitHubActions: pass/fail result
GitHubActions-->>Developer: pull-request comment or dry-run report
Possibly related PRs
🚥 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 |
![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
🧹 Nitpick comments (1)
docs/getting-started.md (1)
30-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winResolve the Markdownlint code-block warnings.
markdownlint-cli2reports MD046 on the fenced blocks and MD014 on command prompts without output.
docs/getting-started.md#L30-L32: use the configured indented style, and remove the$prompt or show command output.docs/getting-started.md#L178-L180: apply the same style and command-prompt fix.docs/index.md#L202-L225: keep the Mermaid block fenced for MkDocs rendering, and add a targeted MD046 exception instead of indenting it.🤖 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/getting-started.md` around lines 30 - 32, Resolve the Markdownlint warnings at docs/getting-started.md lines 30-32 and 178-180 by converting the command blocks to the configured indented style and removing the $ prompts unless command output is shown. Keep the Mermaid block at docs/index.md lines 202-225 fenced for MkDocs rendering and add a targeted MD046 exception for that block.Source: Linters/SAST tools
🤖 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/getting-started.md`:
- Around line 178-180: Update the gh attestation verify command in the
getting-started documentation to pass a single exact wheel path instead of the
commit_check-*.whl glob, or show a loop that verifies each wheel individually.
In `@docs/guides/integrations.md`:
- Around line 50-65: Update the Available hooks documentation to add a short
.pre-commit-config.yaml snippet containing the `- id: check-no-force-push` entry
in the hooks list immediately before the existing `pre-commit install
--hook-type pre-push` command.
---
Nitpick comments:
In `@docs/getting-started.md`:
- Around line 30-32: Resolve the Markdownlint warnings at
docs/getting-started.md lines 30-32 and 178-180 by converting the command blocks
to the configured indented style and removing the $ prompts unless command
output is shown. Keep the Mermaid block at docs/index.md lines 202-225 fenced
for MkDocs rendering and add a targeted MD046 exception for that block.
🪄 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: f3a41b21-f551-4ae7-ad5e-8300b0ab7ace
📒 Files selected for processing (20)
.github/workflows/deploy.ymldocs/changelog.mddocs/configuration.mddocs/example.mddocs/getting-started.mddocs/getting-started/installation.mddocs/getting-started/why.mddocs/guides/ai-attribution.mddocs/guides/github-actions.mddocs/guides/integrations.mddocs/guides/organization.mddocs/guides/policies.mddocs/guides/pre-commit.mddocs/guides/signoff.mddocs/index.mddocs/projects.mddocs/what-is-new.mdmkdocs.ymlnetlify.tomlscripts/mkdocs_hooks.py
💤 Files with no reviewable changes (9)
- docs/guides/signoff.md
- docs/guides/pre-commit.md
- docs/getting-started/why.md
- docs/guides/organization.md
- docs/guides/github-actions.md
- docs/guides/ai-attribution.md
- docs/projects.md
- docs/getting-started/installation.md
- docs/what-is-new.md
Comment on lines
+178
to
+180
| ```console | ||
| $ gh attestation verify commit_check-*.whl --repo commit-check/commit-check | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repo files =="
git ls-files | sed -n '1,120p'
echo "== target lines =="
if [ -f docs/getting-started.md ]; then
nl -ba docs/getting-started.md | sed -n '160,195p'
fi
echo "== attestation occurrences =="
rg -n "gh attestation verify|commit_check-\\*\\.whl" .
echo "== gh attestation CLI help (if installed) =="
if command -v gh >/dev/null 2>&1; then
gh attestation verify --help | sed -n '1,220p'
else
echo "gh not installed"
fiRepository: commit-check/commit-check.com
Length of output: 1132
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== target lines =="
if [ -f docs/getting-started.md ]; then
awk 'NR>=155 && NR<=190 { printf "%4d\t%s\n", NR, $0 }' docs/getting-started.md
fi
echo "== attestation occurrences =="
grep -RIn "gh attestation verify\|commit_check-\*\.whl" . || true
echo "== gh attestation CLI help (if installed) =="
if command -v gh >/dev/null 2>&1; then
gh attestation verify --help | awk 'NR<=240 { print }'
else
echo "gh not installed"
fi
echo "== static glob expansion probe =="
mkdir -p /tmp/attestation-probe
touch "/tmp/attestation-probe/commit_check-1.0.0-py3-none-any.whl"
touch "/tmp/attestation-probe/commit_check-1.0.0-linux_x86_64.whl"
printf 'sh_args='
(cd /tmp/attestation-probe && sh -c 'set -- commit_check-*.whl; printf "%s\n" "$@"' | awk '{ printf "%s ", "\"" $0 "\""; } END { print "" }')Repository: commit-check/commit-check.com
Length of output: 10074
Pass one wheel path to gh attestation verify.
The commit_check-*.whl glob expands to multiple arguments when several platform wheels are present, but this command takes one artifact path. Use one exact wheel path or verify each wheel in a loop.
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 178-178: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 179-179: 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/getting-started.md` around lines 178 - 180, Update the gh attestation
verify command in the getting-started documentation to pass a single exact wheel
path instead of the commit_check-*.whl glob, or show a loop that verifies each
wheel individually.
Comment on lines
+50
to
+65
| ### Available hooks | ||
|
|
||
| | Hook ID | Stage | Rules | | ||
| |---|---|---| | ||
| | `check-message` | `commit-msg` | [CC001–CC013](../rules.md#commit-message-rules) | | ||
| | `check-branch` | `pre-commit` | [CC201–CC202](../rules.md#branch-rules) | | ||
| | `check-author-name` | `pre-commit` | [CC101](../rules.md#cc101) | | ||
| | `check-author-email` | `pre-commit` | [CC102](../rules.md#cc102) | | ||
| | `check-no-force-push` | `pre-push` | [CC301](../rules.md#cc301) | | ||
|
|
||
| `check-no-force-push` also needs its own install: | ||
|
|
||
| ```console | ||
| $ pre-commit install --hook-type pre-push | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Add the missing hook-id snippet for check-no-force-push.
The table lists check-no-force-push as a pre-push hook, but no .pre-commit-config.yaml snippet shows adding - id: check-no-force-push to the hooks list. Line 62-64 only shows pre-commit install --hook-type pre-push. A reader who runs only that command activates the pre-push git hook wiring, but nothing runs at the pre-push stage because the hook itself was never added to the config.
Add a short snippet showing the hook entry before the install command.
📝 Proposed addition
`check-no-force-push` also needs its own install:
+```yaml title=".pre-commit-config.yaml"
+ - id: check-no-force-push
+```
+
```console
$ pre-commit install --hook-type pre-push</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **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.
```suggestion
### Available hooks
| Hook ID | Stage | Rules |
|---|---|---|
| `check-message` | `commit-msg` | [CC001–CC013](../rules.md#commit-message-rules) |
| `check-branch` | `pre-commit` | [CC201–CC202](../rules.md#branch-rules) |
| `check-author-name` | `pre-commit` | [CC101](../rules.md#cc101) |
| `check-author-email` | `pre-commit` | [CC102](../rules.md#cc102) |
| `check-no-force-push` | `pre-push` | [CC301](../rules.md#no-force-push-rules) |
`check-no-force-push` also needs its own install:
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 63-63: 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/guides/integrations.md` around lines 50 - 65, Update the Available hooks
documentation to add a short .pre-commit-config.yaml snippet containing the `-
id: check-no-force-push` entry in the hooks list immediately before the existing
`pre-commit install --hook-type pre-push` command.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #2, which merged the sample-output fix and the missing changelog entries. This is the structural pass.
Why
The site had roughly pre-commit.com's content volume (2.9k lines vs 2.3k) spread across 17 navigation destinations instead of 1. Nine of those pages were under 100 lines. pre-commit.com reads as clear not because it categorises well, but because there is nothing to categorise — one page, one Ctrl-F, one URL.
Four places said the same thing twice:
installation.mdand quickstart step 1quickstart.mdandexample.mdwhat-is-new.mdandchangelog.md— Chore/refresh sample output #2 had to touch both, which is how an entry went missingWhat changed
/getting-started/installation+quickstart/guides/integrations/pre-commit+github-actions+organization/guides/policies/signoff+ai-attribution/why+projects(incl. the architecture diagram)/changelog/what-is-new→ a Highlights tableThe Highlights table links into the entries below rather than restating them, so a release is written up once. All 18 version headings gained stable anchors (
/changelog/#v2130).URLs
/rules/and/configuration/do not move. Every released version of the package printscommit-check.com/rules/#ccNNN— hardcoded asRULES_DOCS_URLincommit_check/rules_catalog.pyand asserted in its tests — so that path is a published interface, not a documentation path.Every retired URL gets a redirect stub emitted by
scripts/mkdocs_hooks.py. Production is GitHub Pages, wherenetlify.tomlhas no effect, so the build hook is the only mechanism that reaches users;netlify.tomlcovers deploy previews only. The forced/getting-started/→/getting-started/quickstart/redirect is removed — it would have shadowed the real page that now lives there.Correctness fixes the merge surfaced
commit-check-action@v1in the GitHub Actions guide. The action has been on v2 since v2.0.0 (latest v2.12.0). Thev1floating tag still resolves, so nothing errored — users just silently got an old action. The landing page already said@v2; the two disagreed.author_name/author_emailin the changelog from Chore/refresh sample output #2. The runtime options areauthor_name_pattern/author_email_pattern.rev:pins spread across four versions (v2.5.0, v2.11.0, v2.12.2 ×2) → v2.13.0. The blog post keeps its own pin; a dated post records what was true when written.v2.11.1was missing entirely from the changelog, and its two signoff fixes (#462, #464) were filed under v2.12.0 where they did not ship.Guards added
mkdocs.ymlturns onvalidation.anchorsandunrecognized_links, so the deploy build's--strictnow fails on a broken anchor. The pages cross-link by section anchor after this change, and a stale anchor is invisible in a rendered page — it just scrolls to the top. Verified by breaking one:Aborted with 1 warnings in strict mode.The docs-sync CI job now installs the released package rather than
main. That exception existed because the rule IDs were merged but unreleased; while it stood, CI was validating the site against code no reader could install. v2.13.0 is on PyPI, so it is over. Left unpinned deliberately — the check only means something against whatpip install commit-checkactually returns.Verification
mkdocs build --strictclean/rules/#cc003intactGenerated by Claude Code
Summary by CodeRabbit