This release is a pre-release and may not be stable for production use.
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_cardsis accepted but ignored. sphinx-gp-opengraph does not bundle the matplotlib-based card generator the upstream ships. Setting the value emits oneWARNINGatconfig-inited:sphinx-gp-opengraph: ogp_social_cards ignored — sphinx-gp-opengraph ships no card generator
Grep your build log for
ogp_social_cards ignoredto 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.xmlemission - gp-sphinx — the umbrella
docs platform; auto-derives
ogp_site_url,ogp_site_name, andogp_imagefrom a singledocs_urlargument - sphinx-gp-opengraph package page — integration story, event hooks, and how-it-works
1 maintainer
Metadata
1 maintainer
Release files for sphinx-gp-opengraph 0.1.0a39
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| sphinx_gp_opengraph-0.1.0a39.tar.gz | 12.0 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinx_gp_opengraph-0.1.0a39-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 24.1 kB
Release files / sphinx_gp_opengraph-0.1.0a39.tar.gz
| Download URL | sphinx_gp_opengraph-0.1.0a39.tar.gz |
|---|---|
| Size | 12.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a77a1152dd708622a4c3b880c5ec2d3fde22c3bf1b4c673c9fd69ac49cf5ba56
|
|
BLAKE2b-256 checksum How to use checksums |
52db3369e9b30c5ccb0387fbb555c84a0613ccb8cc6228962520c7f9e64b9635
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / sphinx_gp_opengraph-0.1.0a39-py3-none-any.whl
| Download URL | sphinx_gp_opengraph-0.1.0a39-py3-none-any.whl |
|---|---|
| Size | 12.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c5718ca342a16c392b56516866f0a75601e735b0a80a366473f61fb55bd9542f
|
|
BLAKE2b-256 checksum How to use checksums |
444779829fcbe064abbf1cd304ec32fd3fd7815bbf2be3e3e3575e968bf13d4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logSecurity for sphinx-gp-opengraph 0.1.0a39
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for sphinx_gp_opengraph-0.1.0a39.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
