docs: rework the README to the org layout and move required tools to the docs

[shenxianpeng]

Part of aligning the READMEs across the org (same layout as cpp-linter/cpp-linter-hooks#289). The README is also the docs home page (between README-start and README-end) and the Marketplace listing.

README

Header

• The H1 is cpp-linter-action.
• Badges: release, ci and part of cpp-linter. The ci badge uses self-test.yml, the workflow that runs the action. The marketplace, cpp-linter.yml, MkDocs Deploy and hub badges are gone.
• The sentence keeps the feature names with their input links. The link line adds Documentation and Marketplace.

Quick start

• It is the website's Get started workflow (format-review) and its four bullets, word for word.
• The thread comment example from docs: fix the usage example and the list of users #491 stays under Usage › "Post a thread comment", unchanged. That includes the fork-safe expression still discussed on docs: fix the usage example and the list of users #491.

Moved: Required tools

• "Required tools installed" moves to a new docs page, docs/required-tools.md, added to the nav after Permissions.
• The text is the same, with one fix: the install order. clang-tools 1.3.0 (pinned in pyproject.toml) tries the static binaries first and falls back to the PyPI wheels, not the other way round (clang_tools/main.py, the install branch). The README keeps a short ## Supported runners section that links to the page.

Used by

• The same 11 organizations, each re-checked on its default branch. "Jupyter" becomes "Jupyter Xeus", the org's name.
• Each entry is the org's avatar and name in one link, instead of the <p align> HTML. The list ends with a link to the showcase.

Removed

• The cpp-linter-hooks tip: the link line and the website cover it.
• "Add C/C++ Linter Action badge in README": its snippet shows this repository's badge, not the user's.
• "Have question or feedback?" becomes ## Contributing.

Docs home page fix

docs/index.md never defined skip-doc, so the live docs home page prints [skip instruction][skip-doc] as text. The README now defines skip-doc and gh-container-syntax inside the included range. docs/index.md gains one line, [tools-doc]: required-tools.md.

Checked

• uv run mkdocs build --strict passes.
• On the built home page, no link reference is left unresolved and the Required Tools link goes to the new page.
• readme_renderer renders the README without warnings.
• All links return 200, except the new docs page URL, which exists once this deploys.
• The repo's pre-commit hooks pass. actionlint finds nothing in the README's YAML blocks.

Summary by CodeRabbit

• Documentation
  • Reorganized the README with project, quick-start, usage, and contributing guidance, including supported LLVM versions and pull-request requirements.
  • Added a required-tools reference covering runner prerequisites and clang-tool installation options.
  • Added the required-tools guide to the documentation navigation.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: fa197b0a-3b21-4d61-abb7-32e852898473

📥 Commits

Reviewing files that changed from the base of the PR and between f2e4501 and 03b075b.

📒 Files selected for processing (4)

• README.md
• docs/index.md
• docs/required-tools.md
• mkdocs.yml

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

Walkthrough

The README now provides a project overview, quick-start and usage examples, supported-runner information, and contribution guidance. A new required-tools guide describes tool installation behavior and runner prerequisites, and is linked from the documentation index and navigation.

Changes

Project and tool documentation

Layer / File(s)	Summary
README overview and usage README.md	The README adds a project overview, quick-start workflow, thread-comment example, supported-runner section, and contribution guidance. It replaces the former organization-logo block with a linked organization list.
Runner and tool requirements README.md, docs/required-tools.md, docs/index.md, mkdocs.yml	The README links to the required-tools guide and removes its detailed tool installation descriptions. The new guide documents Nushell and uv, Linux prerequisites, and clang-tool sources for Linux, macOS, and Windows. The guide is added to the documentation index and navigation.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 03b07

This change reorganizes the README and adds a Required Tools page linked from the docs index and navigation. It does not change runtime behavior, and no merge-blocking issue was found.

Architecture Summary

Architecture risk: 🔵 Low · up to 03b07

The change affects 3 systems.

Changed systems: docs, mkdocs.yml, README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — docs (service) was modified; 2 changed files map to changed impact.
• observed — mkdocs.yml (service) was modified; 1 changed file maps to changed impact.
• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: The markdownlint directive now disables only MD041; MD033 is no longer disabled.
• observed — Modified behavior in README.md: The required-tools documentation link replaces the GitHub workflow-skip documentation link in this link-definition location.
• observed — Modified behavior in README.md: The former title, badges, and usage setup are replaced with a project heading, release/CI/project badges, a concise action description, navigation links, and the beginning of a quick-start workflow.
• observed — Modified behavior in README.md: The quick-start example grants pull-request write permission, sets clang version 21, enables file style and format reviews, and fails the job when checks-failed is positive. Its accompanying notes document configuration defaults, supported LLVM versions, opt-in review/comment permissions, auto-fix permissions, and fork/draft behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: restructuring the README and moving required-tools content into the documentation.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}