Skip to content

Add section-aware OG images for docs previews #294

@BrianSeong99

Description

@BrianSeong99

Problem

The docs site currently uses one global social preview image for every page. When a specific docs URL is shared in Twitter/X, Telegram, Slack, or other unfurlers, the title and description may be page-specific, but the preview image does not communicate the page's section or context.

This makes shared docs links look generic and less useful, especially for index pages and important builder/core-concepts sections.

Proposed scope

Add a section-aware Open Graph / Twitter preview image system:

  • Keep page title and description page-specific for SEO and link previews.
  • Use dedicated OG images for major index pages and sections.
  • If the shared page is an index page, show that index page's own preview image.
  • If the shared page is a detailed child page, use the nearest parent/index/category preview image.
  • Keep a global fallback image for pages that do not match a known section.
  • Generate 1200x630 PNG assets so previews work reliably across Twitter/X, Telegram, Slack, Discord, and other unfurlers.
  • Centralize routing logic so individual docs pages do not need manual image: front matter unless they need a special override.

Initial section image candidates

  • Miden Docs / global fallback
  • Build
  • Get Started
  • Smart Contracts
  • Tutorials
  • Tools
  • Clients
  • React SDK
  • Rust Client
  • Note Transport
  • Miden Guardian
  • Private Multisig
  • Core Concepts
  • Protocol
  • Node
  • Miden VM
  • Compiler

Acceptance criteria

  • Docusaurus emits page-specific title/description metadata unchanged.
  • Docusaurus emits section-aware og:image / twitter:image metadata for docs pages.
  • Explicit front matter image: still overrides the automatic section image.
  • Generated images are committed under static/img/og/ or an equivalent static path.
  • The visual design reads as Miden documentation, not just a logo pasted onto a static background.
  • npm run build passes.
  • At least a few built pages are checked for the expected metadata, including an index page and a detailed child page.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions