Sphinx Open Graph Extension

0.13.0 · active · verified Mon Apr 13

sphinxext-opengraph is a Sphinx extension that automatically generates Open Graph Protocol (OGP) metadata for each page of your documentation. This enables rich previews when documentation links are shared on social media platforms. The current version is 0.13.0, and the project maintains an active release cadence with regular updates and support for recent Sphinx and Python versions.

Warnings

breaking Support for Sphinx 4 was dropped in version 0.10.0. Projects using older Sphinx versions should upgrade `sphinxext-opengraph` cautiously or stick to an older version.
Fix: Upgrade your Sphinx version to 5 or higher. If you need to stay on Sphinx 4, use `sphinxext-opengraph<0.10.0`.
breaking Python 3.7 support was dropped in version 0.9.0. Users on Python 3.7 must upgrade their Python environment or remain on `sphinxext-opengraph<0.9.0`.
Fix: Upgrade to Python 3.8 or newer. If you must use Python 3.7, use `sphinxext-opengraph<0.9.0`.
gotcha The `ogp_site_url` configuration option is critical. Without it, or if it's set incorrectly, the Open Graph metadata will not include absolute URLs and may not be properly recognized by social media platforms. Read the Docs users typically do not need to set this, as it is automatically detected.
Fix: Ensure `ogp_site_url` is explicitly set in `conf.py` to the canonical public URL of your documentation, e.g., `ogp_site_url = "https://docs.example.com/"`.
gotcha Generating social media cards (`ogp_social_cards`) requires the optional `matplotlib` dependency. Furthermore, images used for social cards (e.g., `html_logo` or `ogp_social_cards['image']`) cannot be in SVG format due to Matplotlib limitations.
Fix: Install with `pip install sphinxext-opengraph[social_cards]`. Ensure any images intended for social cards are PNG or JPEG.
gotcha When overriding Open Graph tags on a per-page basis using reStructuredText field lists (e.g., `:og:image:`), relative file paths for images, videos, and audio are not supported. Only absolute URLs can be used in these per-page overrides.
Fix: Use absolute URLs for image, video, or audio paths when specifying them via per-page field lists.

Install

pip install sphinxext-opengraph Base installation
pip install sphinxext-opengraph[social_cards] With social card generation

Imports

sphinxext.opengraph
```
# In conf.py
extensions = [
    'sphinxext.opengraph',
    # ... other extensions
]
```
Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not via Python 'import' statements in user code.

Quickstart

To enable the extension, add 'sphinxext.opengraph' to the `extensions` list in your Sphinx project's `conf.py` file. The `ogp_site_url` configuration option is mandatory and must be set to the public URL of your documentation for Open Graph tags to function correctly. Optional settings like `ogp_image` and `ogp_social_cards` can further customize the generated metadata and social media previews.

# conf.py

extensions = [
    'sphinxext.opengraph',
]

# REQUIRED: Set the public URL where your documentation is hosted
ogp_site_url = "https://docs.example.com/"

# Optional: Set a default image for pages without one
ogp_image = "https://docs.example.com/_static/logo.png"

# Optional: Enable social card generation (requires matplotlib extra)
ogp_social_cards = {
    "enable": True,
    "image": "_static/social_card_logo.png", # Path relative to HTML output root
}

view raw JSON →