sphinxext-opengraph

sphinxext-opengraph is a Sphinx extension that hooks into the HTML build process to emit Open Graph (og:*) meta tags for every page of a documentation site, so links shared on Slack, Twitter/X, Discord, and other platforms render rich previews with a title, description, and image instead of a bare URL.

It requires almost no setup: adding the extension and a single ogp_site_url value to conf.py is enough to get working previews, with an auto-description pulled from each page’s content, automatic Read the Docs canonical-URL detection, and an optional matplotlib-powered social card generator that renders a per-page preview image when no image is otherwise configured.

What You Get

• Automatic og:title, og:type, og:url, og:site_name, and og:description tags generated from each page’s title and content
• A doctree-walking description extractor that trims page text to a configurable length while skipping admonitions, comments, and raw/code blocks
• Optional auto-generated social preview card images (via matplotlib) for pages that don’t set an explicit og:image
• Per-page field-list overrides (:og:title:, :og:image:, :ogp_disable:, arbitrary :og:*: tags) for fine-grained control without touching conf.py
• Automatic canonical-URL detection when hosted on Read the Docs, via the READTHEDOCS_CANONICAL_URL environment variable
• Support for using a page’s first embedded image as its og:image via ogp_use_first_image

Common Use Cases

• Rich link previews for docs sites - project maintainers add the extension so links to their Sphinx-built documentation show a title, summary, and image when shared in Slack, Discord, or social media
• Read the Docs projects - RTD-hosted projects get correct canonical URLs automatically, with no manual ogp_site_url configuration required
• Per-page metadata overrides - technical writers override the auto-generated description or image on specific high-traffic pages using RST field lists
• Automatic social card generation - projects without hand-designed preview images enable ogp_social_cards to have per-page PNG cards rendered at build time

Under The Hood

Architecture The extension’s entire integration surface is a single setup(app) function that registers ten typed config values (ogp_site_url, ogp_image, ogp_social_cards, etc.) via app.add_config_value and connects one callback, html_page_context, to Sphinx’s html-page-context build event. That callback delegates to get_tags(), which assembles an og:* tag dictionary from the page’s rendered context, its docutils doctree, and the active Sphinx config. Supporting concerns are cleanly separated into single-purpose modules: _title_parser.py extracts and HTML-strips the page title, _meta_parser.py reads any existing <meta name="description"> tag, and _description_parser.py implements a docutils.nodes.NodeVisitor (DescriptionParser) that walks the doctree collecting leaf-node text while skipping admonitions, raw nodes, and code blocks, truncating once a configured length is hit. The optional social-card renderer (_social_cards.py) is imported behind a try/except ImportError, so the whole feature degrades gracefully when matplotlib isn’t installed. Because there’s a single call site (get_tags) building the tag dict, changes to tag precedence or the per-page field-list override logic affect every generated page uniformly, keeping the mental model small. Tech Stack Built for Python 3.9+ and packaged with flit_core via a modern PEP 621 pyproject.toml. The only hard runtime dependency is Sphinx>=6.0 (which pulls in docutils); an optional social_cards extra adds matplotlib>=3 for image rendering. Development uses uv dependency groups for docs (furo, sphinx-design, pinned sphinx~=8.1.0), linting (ruff==0.11.4), packaging (build, twine, pypi-attestations), and testing (pytest==7.4.4, beautifulsoup4 for parsing rendered HTML in tests). CI runs on GitHub Actions across a matrix of Python versions (3.9 through 3.14) and multiple Sphinx versions, plus separate workflows for documentation rendering and PyPI releases. Code Quality The test suite is extensive relative to the codebase’s size: tests/test_options.py covers dozens of scenarios (basic tag generation, description truncation, HTML escaping, per-page overrides, image handling, sitename resolution, Read the Docs detection, social cards) against more than thirty minimal fixture Sphinx projects under tests/roots/, exercised through pytest-sphinx style fixtures in conftest.py and asserted against parsed HTML via BeautifulSoup. Ruff is configured with an unusually strict rule set (flake8-annotations, flake8-bugbear, flake8-blind-except, pydocstyle, flake8-datetimez, and more), and from __future__ import annotations is used project-wide for consistent typing. Error handling is explicit rather than silent: the only exception-swallowing is a deliberate try/except ImportError that disables social cards with a printed warning when matplotlib is absent. API Design Configuration follows Sphinx’s own idioms closely: every option is registered through add_config_value with an explicit allowed-type set, so misconfigured values fail predictably rather than silently. Per-page field-list overrides let authors adjust or disable metadata on individual pages without editing conf.py, and arbitrary og:* field-list keys pass through unchanged, so unsupported Open Graph properties never require an extension update. Read the Docs projects get working canonical URLs with zero configuration, which removes the most common source of setup friction for this kind of tool.