Skip to content

feat: Add generated Open Graph images for docs pages - #769

Open
developerjamiu wants to merge 2 commits into
mainfrom
open-graph-images
Open

feat: Add generated Open Graph images for docs pages#769
developerjamiu wants to merge 2 commits into
mainfrom
open-graph-images

Conversation

@developerjamiu

@developerjamiu developerjamiu commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Every docs page now gets a social card in the style of the serverpod.dev feature pages when its link is shared. Pages with an explicit image in frontmatter keep it.

Screenshots

Creating endpoint methods
card-creating-endpoints

Database backups (Cloud)
card-database-backups

Migrations
card-database-migrations

docs home
card-docs-home

How it works

  • A local plugin (plugins/open-graph-images) renders a 1200x630 JPEG per unique card at build time: the feature-page gradient, the Serverpod logo, the page's sidebar icon, its title, and its description.
  • The icon comes from the page's sidebar_class_name or the nearest sidebar category icon, mirroring the sidebar CSS. The numbered tutorial-step icons are swapped for semantic ones on cards, which adds one new icon SVG.
  • Card identity is a content hash of title, description, icon, and a render fingerprint covering the fonts, icon SVGs, renderer source, and library versions. The swizzled DocItem/Metadata computes the same ID client-side, so no manifest is needed and identical cards dedupe across doc versions: 383 unique cards cover 1632 pages (about 30 MB of images).
  • Rendering is deterministic. sharp, opentype.js, and the DejaVu fonts are pinned exactly, and text is converted to SVG paths.
  • A title or description character the pinned font cannot render fails the build with an error naming the character, so unsupported metadata is caught in CI rather than shipping a broken card.

Verification

  • 20 unit tests covering ID parity between the generator and the theme, icon-map parity with the sidebar CSS, cache invalidation, and failure recovery. They run in CI before the build step.
  • Full production build: every docs page's og:image resolves to an emitted file, with zero broken references and zero orphaned files. The only pages without cards are the 404 page and redirect stubs.

The second commit separately removes leftover Docusaurus template comments from docusaurus.config.js.

@developerjamiu developerjamiu self-assigned this Aug 31, 2026
@developerjamiu developerjamiu added the enhancement New feature or request label Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant