docs: add social cards and cut the two pages that repeated themselves - #517

Two follow-ups from #515.

Social cards

Sharing a documentation link produced a bare URL with no preview image. The social plugin now renders one card per page, and each page carries the og:image tag pointing at it.

Verified locally rather than assumed — 17 cards generated, at the size the platforms expect:

site/assets/images/social/rules.png   1200x630   95% #2c9ccd, 3% white
<meta property="og:image" content="https://docs.commit-check.com/assets/images/social/rules.png" />

Deploy previews skip the cards. Nobody shares a preview link for its preview image, and skipping them keeps those builds fast and free of the system cairo dependency that rendering needs:

default            17 cards, og:image present
SOCIAL_CARDS=false  0 cards, build still succeeds

The GitHub Pages job installs libcairo2 explicitly. cairosvg dlopens it at runtime rather than bundling it, and I could not verify whether the runner image already carries it — so the workflow no longer depends on that being true.

The two leftover pages

Both were carried over from the Sphinx site converted but not rewritten, and both had since been overtaken by the pages written around them.

example.md — 374 → 191 lines. It opened with "Running as GitHub Action" and "Running as pre-commit hook", which now have guides of their own that go considerably further. Removed. What remains is what its navigation entry already called it: recipes for invoking the CLI — checking a message from the repository, a file or stdin; branch, committer and force-push checks; pointing at a different config; and the output formats a script actually reaches for.

The jq example was checked against real output, not written from memory — my first attempt used select(.passed | not), and the field is status:

$ commit-check -m --format json | jq -r '.checks[] | select(.status == "fail") | .rule_id'
CC001

what-is-new.md — 365 → 76 lines. It re-explained every feature a second time, next to a changelog that already recorded them and guides that now document them properly. Every section had somewhere better to point: AI attribution to its guide and CC013, force push to CC301, inherit_from to the organization guide, 2.0.0 to the migration page. It is now an index — what changed, why it mattered, and a link — with the changelog remaining the full record.

Testing

$ mkdocs build --strict     # zero warnings, both card modes
$ pytest tests/ -q
460 passed

Cross-page anchors used by the rewritten pages were checked against the rendered HTML (example/#blocking-force-pushes, example/#output-for-scripts-and-ci) rather than assumed to exist.

The one failing test, test_load_config_file_permission_error, reproduces on main and is unrelated: it uses os.chmod(0o000), which does not restrict root.

Summary by CodeRabbit

• Documentation

  • Replaced the usage guide with a concise command-line recipes reference covering common commands, output formats, scripting, configuration, and hook guidance.
  • Simplified release highlights for versions 2.11.0 through 2.0.0, with focused examples and links to detailed documentation.
  • Added support for social preview cards on documentation pages.

• Chores

  • Improved documentation build reliability and excluded local cache directories from version control.