sphinx-gp-opengraph 0.0.1a18.dev0

OpenGraph and Twitter meta-tag emission for Sphinx — matplotlib-free

sphinx-gp-opengraph

OpenGraph meta-tag emission for Sphinx — a drop-in replacement for sphinxext-opengraph that ships every ogp_* config key the upstream supports, minus the matplotlib-based social-card generator. No image-rendering dependencies, no system-fontconfig surprises.

Part of the gp-sphinx documentation platform.

Install

$ pip install sphinx-gp-opengraph

When you depend on gp-sphinx, this extension is already loaded — see Auto-derived values below. The full config-key reference is auto-generated on the package docs page from the live app.add_config_value() registrations.

Minimum viable conf.py

extensions = [
    "sphinx_gp_opengraph",
]

ogp_site_url = "https://example.com/"

ogp_image = "_static/og-default.png"

A 1200×630 PNG works on Slack, Facebook, LinkedIn, and X/Twitter unfurlers. With these three values set, every page rendered by an HTML-family builder gains og:title, og:type, og:url, og:site_name, og:description, og:image, and og:image:alt. A matching <meta name="description"> is emitted when the page does not already define one.

Auto-derived values when used with gp-sphinx

Projects that build through {py:func}gp_sphinx.config.merge_sphinx_config do not need to set ogp_site_url, ogp_site_name, or ogp_image manually. Pass docs_url= to merge_sphinx_config() and gp-sphinx fills all three from that one value. See the sphinx-gp-opengraph package page for the integration story and configuration.md for the canonical mapping table.

Per-page overrides

Set front-matter fields to override the site-wide defaults on a single page. MyST syntax shown; reST field-list syntax behaves the same way.

---
ogp_description_length: 160
og:image: _static/og/this-page.png
og:image:alt: A tailored hero for this page
---

# Page title

Body paragraph that becomes og:description.

Field	Effect
og:image	Replace the site-default image for this page
og:image:alt	Replace the alt text for this page
ogp_description_length	Override the description-length cap for this page
ogp_disable: true	Skip OpenGraph emission entirely on this page

Any other og:* field-list entry is forwarded to the page head verbatim, so og:type, og:audio, etc. work without code changes.

Twitter cards

sphinx-gp-opengraph does not register a separate twitter_* namespace; crawlers fall back to og:* for most fields. Append explicit Twitter markup through ogp_custom_meta_tags when you need it:

ogp_custom_meta_tags = [
    '<meta name="twitter:card" content="summary_large_image" />',
    '<meta property="og:image:width" content="1200" />',
    '<meta property="og:image:height" content="630" />',
]

Migration from sphinxext-opengraph

Configuration is drop-in compatible — every ogp_* key is registered with the same name, type, and default — with one behavioural change:

• ogp_social_cards is accepted but ignored. sphinx-gp-opengraph does not bundle the matplotlib-based card generator the upstream ships. Setting the value emits one WARNING at config-inited:

  sphinx-gp-opengraph: ogp_social_cards ignored — sphinx-gp-opengraph ships no card generator
  

  Grep your build log for ogp_social_cards ignored to find this warning. The replacement workflow lives in the next section.

The recommended replacement is one static PNG per page. Drop them under _static/og/ and point the per-page og:image field-list entry at each one. The downstream UX is the same as upstream's auto-generated cards — just explicit, and with no build-time dependency on matplotlib or PIL.

docs/
├── _static/
│   └── og/
│       ├── default.png
│       ├── quickstart.png
│       └── reference.png
├── quickstart.md
└── reference.md

---
og:image: _static/og/quickstart.png
---

# Quickstart

See also

• sphinx-gp-sitemap — companion package for sitemap.xml emission
• gp-sphinx — the umbrella docs platform; auto-derives ogp_site_url, ogp_site_name, and ogp_image from a single docs_url argument
• sphinx-gp-opengraph package page — integration story, event hooks, and how-it-works