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.
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:
image:front matter unless they need a special override.Initial section image candidates
Acceptance criteria
og:image/twitter:imagemetadata for docs pages.image:still overrides the automatic section image.static/img/og/or an equivalent static path.npm run buildpasses.