docs: generate page-specific social preview images

[jdx]

Shared documentation links now display the page title alongside hk's branding in a generated 1200×630 PNG. Open Graph and Twitter reference the same image with descriptive alt text; content-based URLs refresh when the title or artwork changes.

The build renders locally using resvg and a bundled OFL-licensed Space Grotesk font. The renderer handles long titles and CLI command names without overlapping the logo. Added renderer tests and built-HTML checks to docs:build.

Validation: production docs build passed, all three renderer tests passed, and social metadata and emitted PNG dimensions were verified for 75 pages. Visually reviewed the rendered previews.

AI-assisted — Tool: Codex; model: OpenAI/GPT-6; version: unavailable.

---

Note

Low Risk
Changes are limited to the docs VitePress build and social metadata; no runtime product or security-sensitive paths.

Overview
Documentation links no longer share a single og.png preview. Each VitePress page now gets a 1200×630 social card built from that page’s heading (homepage uses a fixed tagline), hk branding, and the existing logo.

Cards are rendered at build time via social-images.mjs using @resvg/resvg-js and bundled Space Grotesk (no external renderer or system fonts). PNG filenames are keyed by a hash of the image bytes so title, layout, font, or renderer changes get new URLs. transformHead writes the PNG into social/ and sets matching Open Graph and Twitter image tags plus {heading} — hk docs alt text.

docs:build now runs unit tests for wrapping/truncation and a post-build check-social-images.mjs pass that verifies metadata, dimensions, per-page image bytes, and rejects swapped or empty alt text.

^{Reviewed by Cursor Bugbot for commit 2cf143b. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Documentation pages now generate unique social preview images from each page’s heading.
  • Social cards use consistent branding, 1200×630 PNGs, and matching Open Graph and Twitter metadata.
  • Long page titles are automatically wrapped and shortened for clear previews.

• Documentation

  • Added guidance for social preview generation, bundled fonts, and licensing.

• Bug Fixes

  • Added build checks for image dimensions, metadata, output files, accessibility text, and title rendering.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​resvg/​resvg-js@​2.6.2

View full report

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Team

Run ID: 3b22ead6-f3a3-47ac-abe4-d1d1ebe7e873

📥 Commits

Reviewing files that changed from the base of the PR and between 98ce2d3 and 2cf143b.

📒 Files selected for processing (6)

• docs/.vitepress/SOCIAL-IMAGES.md
• docs/.vitepress/check-social-images.mjs
• docs/.vitepress/fonts/OFL.txt
• docs/.vitepress/fonts/README.md
• docs/.vitepress/social-images.mjs
• docs/.vitepress/social-images.test.mjs

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/.vitepress/fonts/OFL.txt
• docs/.vitepress/fonts/README.md
• docs/.vitepress/SOCIAL-IMAGES.md

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The docs build now generates page-specific 1200×630 social cards with bundled fonts and Resvg. VitePress emits each card in page metadata. Tests and a post-build script validate wrapping, PNG output, metadata, dimensions, and distinct images.

Changes

Social image generation

Layer / File(s)	Summary
Card generation and rendering docs/.vitepress/social-images.mjs, docs/.vitepress/fonts/*, docs/.vitepress/social-images.test.mjs, docs/package.json, aube-lock.yaml	The generator wraps and escapes titles, embeds the logo and Space Grotesk font, renders hashed PNG files, and tests dimensions, escaping, hashing, and wrapping. Resvg is added as a docs devDependency with platform-specific lockfile entries.
Build integration and validation docs/.vitepress/config.mts, docs/.vitepress/check-social-images.mjs, docs/.vitepress/SOCIAL-IMAGES.md, docs/package.json	VitePress generates per-page social metadata and images. The build runs generator tests and validates emitted HTML, metadata, PNG signatures, dimensions, and distinct image output.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 2cf14

Documentation pages now publish title-specific social preview cards with matching Open Graph and Twitter metadata. The generated images and metadata are validated during the docs build, with no concrete current-head merge-blocking risk identified.

Sequence Diagram(s)

sequenceDiagram
  participant VitePress
  participant socialCard
  participant writeSocialCard
  participant Resvg
  participant Validator
  VitePress->>socialCard: Build card from page heading
  socialCard->>Resvg: Render SVG as PNG
  Resvg-->>socialCard: Return PNG bytes and hashed path
  VitePress->>writeSocialCard: Write PNG and metadata URL
  Validator->>VitePress: Scan generated pages
  Validator->>socialCard: Generate expected card
  socialCard-->>Validator: Return expected PNG and path

Loading

Poem

A rabbit wraps titles in lines neat and bright
Resvg renders each card into light
Hashed PNGs rest in their folders with care
Tests check the pixels and metadata there
The docs build confirms each image is right
And hops through the pages by preview-card light

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: generating page-specific social preview images for the documentation site.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. (3 skipped: 3 …
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.

---

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.}

[greptile-apps]

Greptile Summary

This PR generates page-specific 1200×630 social preview images during the documentation build.

• Renders cards locally with resvg and a bundled Space Grotesk font.
• Adds page-specific Open Graph and Twitter metadata.
• Uses a digest of the final PNG bytes for cache-safe image URLs.
• Adds renderer tests and built-site validation for metadata, image content, and dimensions.

Confidence Score: 5/5

The PR appears safe to merge, with the previous image-cache finding fully addressed and no new actionable defects identified.

Social image filenames are now derived from the exact PNG bytes that are written, so renderer and rendering-option changes produce fresh URLs. The expanded build checks consistently validate page metadata and emitted image content.

Important Files Changed

Filename	Overview
docs/.vitepress/social-images.mjs	Renders, content-addresses, and writes deterministic social-preview PNGs; the previous cache-key issue is fully fixed.
docs/.vitepress/config.mts	Generates each page’s card and injects matching Open Graph and Twitter metadata.
docs/.vitepress/check-social-images.mjs	Validates built metadata against regenerated page-specific cards and checks emitted PNG contents and dimensions.
docs/.vitepress/social-images.test.mjs	Covers escaping, wrapping, truncation, rendering, final-PNG hashing, swapped images, and empty alt text.
docs/package.json	Integrates renderer tests and post-build social-image checks into docs:build.
aube-lock.yaml	Locks resvg and its platform-specific native packages.

_{Reviews (2): Last reviewed commit: "docs: address social preview review feed..." | Re-trigger Greptile}