doc: add Open Graph meta tags for link previews - #694
Merged
Conversation
Links to the documentation shared on social media platforms render without a preview card, as generated HTML pages carry no Open Graph metadata. Enable the sphinxext-opengraph extension to produce these meta tags on every page. Point the Open Graph image tag to a new PNG rendering of the project logo, sized 1200 by 630 pixels, since SVG images are not supported by social media platforms, and request the large preview card layout on X/Twitter. On Read The Docs, page and image URLs are resolved against the canonical URL of the exact documentation version being built, so every published version gets correct metadata. A fallback site URL pointing to the latest version is used for builds outside of Read The Docs. The extension is added to the Read The Docs build requirements and is skipped when unavailable, so local documentation builds keep working without it. Assisted-by: Claude:claude-fable-5 Signed-off-by: Xavier Delaruelle <xavier.delaruelle@cea.fr>
xdelaruelle
force-pushed
the
opengraph-preview
branch
from
August 29, 2026 07:10
a7fb764 to
fd288d5
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Links to the documentation shared on social media platforms currently render without a preview card, as the generated HTML pages carry no Open Graph metadata. Enable the sphinxext-opengraph extension to produce these meta tags on every page, and point the Open Graph image tag to a new PNG rendering of the project logo (1200x630 pixels, as SVG images are not supported by social media platforms). The
twitter:cardtag requests the large preview card layout on X/Twitter; Bluesky, Mastodon and LinkedIn build their preview cards from the standard Open Graph tags.On Read The Docs, page and image URLs are resolved against the canonical URL of the exact documentation version being built (through the
READTHEDOCS_CANONICAL_URLenvironment variable), so every published version gets correct metadata. A fallback site URL pointing to the latest version is used for builds outside of Read The Docs.The extension is added to the Read The Docs build requirements and is skipped when unavailable, so local documentation builds keep working without it.