sphinx-gp-opengraph¶

Alpha

Rendered output is stable. The Python API and Sphinx config value names may change without a major version bump. Pin your dependency to a specific version range in production.

OpenGraph meta-tag emission for Sphinx. The package registers every ogp_* config value the upstream sphinxext-opengraph exposes and emits the same <meta> tags, with one deliberate omission: the matplotlib-based social-card generator is not bundled. That is why the package has zero non-Sphinx runtime dependencies.

For install, per-page overrides, Twitter-card markup, and the verbatim deprecation-warning text, see the package README. This page covers integration with gp-sphinx, the emission pipeline, the trade-offs, and the auto-generated config-value reference.

Integration with gp-sphinx¶

sphinx_gp_opengraph ships in DEFAULT_EXTENSIONS, so projects that build through merge_sphinx_config() load it automatically. Passing docs_url= to that function auto-derives three of the most common config values:

Auto-derived	Source
`ogp_site_url`	`docs_url`
`ogp_site_name`	`project`
`ogp_image`	`"_static/img/icons/icon-192x192.png"`

The canonical reference for these and the other auto-derived values lives in From docs_url. Any value passed via **overrides to merge_sphinx_config() wins over the auto-derived default — auto-computation runs first, overrides apply last.

How the page-level meta tags are built¶

For every page rendered by an HTML-family builder, the extension’s html-page-context handler walks the resolved doctree and emits the following tags into context["metatags"]. The page is skipped when its front-matter sets ogp_disable: true.

Tag	Source
`og:title`	First heading of the page, with HTML stripped (`_title.py`)
`og:type`	`ogp_type` (default `"website"`)
`og:url`	`ogp_canonical_url or ogp_site_url`, joined with the page’s relative URL
`og:site_name`	`ogp_site_name`, or `project` when unset; suppressed when set to `False`
`og:description`	First non-title body paragraph, truncated to `ogp_description_length`, HTML-escaped (`_description.py`)
`og:image`	Page front-matter `og:image`, else `ogp_image`, else first in-page image when `ogp_use_first_image=True`
`og:image:alt`	Front-matter `og:image:alt`, else `ogp_image_alt`, falling back to site name, then page title
`<meta name="description">`	Mirror of `og:description` when `ogp_enable_meta_description=True` and the page does not already define one (`_meta.py`)

The description extractor walks the document, skips title nodes and empty paragraphs, takes the first prose paragraph, and truncates at the configured cap. Embedded HTML quote characters are escaped with " before emission, so user content cannot break out of the attribute value.

Custom raw markup listed in ogp_custom_meta_tags is appended verbatim after the structured tags — that is the supported escape hatch for Twitter card declarations and og:image:width/og:image:height hints.

Event hooks¶

config-inited     →  _warn_if_social_cards_used     (deprecation warning)
html-page-context →  html_page_context              (per-page meta-tag emission)

Both hooks live in sphinx_gp_opengraph/__init__.py. There is no builder-inited or build-finished work — the extension is purely a per-page transformer.

Trade-offs¶

ogp_social_cards is accepted but ignored. The upstream extension ships a matplotlib renderer that builds per-page PNGs at builder-inited. sphinx-gp-opengraph deliberately omits the dependency to keep the install graph small. The config key remains registered so existing conf.py files do not error; setting it logs a single WARNING at config-inited directing users to the static-image workflow documented in the README.

parallel_read_safe and parallel_write_safe are both True. The extension never writes shared state — every emission is self-contained inside the per-page hook — so it is safe under any sphinx-build -j N value.

Config reference¶

Generated from app.add_config_value() registrations in sphinx_gp_opengraph/__init__.py.

Config Value Index

Name	Type	Default	Rebuild
`ogp_site_url`	`str`	`''`	`html`
`ogp_canonical_url`	`str`	`''`	`html`
`ogp_description_length`	`int`	`200`	`html`
`ogp_image`	`None \| str`	`None`	`html`
`ogp_image_alt`	`None \| bool \| str`	`None`	`html`
`ogp_use_first_image`	`bool`	`False`	`html`
`ogp_type`	`str`	`'website'`	`html`
`ogp_site_name`	`None \| bool \| str`	`None`	`html`
`ogp_social_cards`	`None \| dict`	`None`	`html`
`ogp_custom_meta_tags`	`list \| tuple`	`()`	`html`
`ogp_enable_meta_description`	`bool`	`True`	`html`

ogp_site_url ¶ config html

Site base URL joined with each page’s relative path to form og:url. Required for absolute URLs; auto-derived from docs_url under gp-sphinx.

Type:: str
Default:: ''
Registered by:: sphinx_gp_opengraph.setup()

ogp_canonical_url ¶ config html

Separate canonical URL used to build og:url; falls back to ogp_site_url when empty.

Type:: str
Default:: ''
Registered by:: sphinx_gp_opengraph.setup()

ogp_description_length ¶ config html

Truncation cap (characters) applied to og:description after extracting the first body paragraph.

Type:: int
Default:: 200
Registered by:: sphinx_gp_opengraph.setup()

ogp_image ¶ config html

Site-default OpenGraph image path or absolute URL. Auto-derived from docs_url under gp-sphinx; per-page og:image front-matter overrides.

Type:: None | str
Default:: None
Registered by:: sphinx_gp_opengraph.setup()

ogp_image_alt ¶ config html

Alt text for ogp_image. Falls back to og:site_name then og:title; False suppresses the alt tag entirely.

Type:: None | bool | str
Default:: None
Registered by:: sphinx_gp_opengraph.setup()

ogp_use_first_image ¶ config html

When True and no per-page override is set, use the first in-page image as og:image.

Type:: bool
Default:: False
Registered by:: sphinx_gp_opengraph.setup()

ogp_type ¶ config html

Value emitted as the og:type tag.

Type:: str
Default:: 'website'
Registered by:: sphinx_gp_opengraph.setup()

ogp_site_name ¶ config html

Value emitted as og:site_name. Defaults to the Sphinx project name; False suppresses the tag.

Type:: None | bool | str
Default:: None
Registered by:: sphinx_gp_opengraph.setup()

ogp_social_cards ¶ config html

Accepted-but-ignored compatibility shim for upstream sphinxext-opengraph. Setting any value emits a one-line WARNING at config-inited; provide a static PNG via ogp_image or per-page og:image instead.

Type:: None | dict
Default:: None
Registered by:: sphinx_gp_opengraph.setup()

ogp_custom_meta_tags ¶ config html

Raw <meta> tag strings appended verbatim after the structured og:* block — the supported escape hatch for Twitter card declarations and image-dimension hints.

Type:: list | tuple
Default:: ()
Registered by:: sphinx_gp_opengraph.setup()

ogp_enable_meta_description ¶ config html

When True, emit a <meta name="description"> mirroring og:description unless the page already defines one.

Type:: bool
Default:: True
Registered by:: sphinx_gp_opengraph.setup()

Package reference¶

Copyable config snippet

extensions = [
    "sphinx_gp_opengraph",
]

Package metadata

Source on GitHub: sphinx-gp-opengraph
PyPI: sphinx-gp-opengraph
Maturity: Alpha

Source on GitHub · PyPI