{"id":5498,"library":"sphinxext-opengraph","title":"Sphinx Open Graph Extension","description":"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.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinxext-opengraph/","tags":["sphinx","documentation","opengraph","seo","social media","extension"],"install":[{"cmd":"pip install sphinxext-opengraph","lang":"bash","label":"Base installation"},{"cmd":"pip install sphinxext-opengraph[social_cards]","lang":"bash","label":"With social card generation"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to operate.","package":"Sphinx","optional":false},{"reason":"Required for generating social media card PNGs. Can be installed with the `social_cards` extra.","package":"matplotlib","optional":true}],"imports":[{"note":"Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not via Python 'import' statements in user code.","symbol":"sphinxext.opengraph","correct":"# In conf.py\nextensions = [\n    'sphinxext.opengraph',\n    # ... other extensions\n]"}],"quickstart":{"code":"# conf.py\n\nextensions = [\n    'sphinxext.opengraph',\n]\n\n# REQUIRED: Set the public URL where your documentation is hosted\nogp_site_url = \"https://docs.example.com/\"\n\n# Optional: Set a default image for pages without one\nogp_image = \"https://docs.example.com/_static/logo.png\"\n\n# Optional: Enable social card generation (requires matplotlib extra)\nogp_social_cards = {\n    \"enable\": True,\n    \"image\": \"_static/social_card_logo.png\", # Path relative to HTML output root\n}","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Sphinx version to 5 or higher. If you need to stay on Sphinx 4, use `sphinxext-opengraph<0.10.0`.","message":"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.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Upgrade to Python 3.8 or newer. If you must use Python 3.7, use `sphinxext-opengraph<0.9.0`.","message":"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`.","severity":"breaking","affected_versions":">=0.9.0"},{"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/\"`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install with `pip install sphinxext-opengraph[social_cards]`. Ensure any images intended for social cards are PNG or JPEG.","message":"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.","severity":"gotcha","affected_versions":"All versions with social card feature (>=0.8.0)"},{"fix":"Use absolute URLs for image, video, or audio paths when specifying them via per-page field lists.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}