Pre-release

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_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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_gp_opengraph-0.1.0a38.tar.gz (12.0 kB view details)

Uploaded Aug 30, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sphinx_gp_opengraph-0.1.0a38-py3-none-any.whl (12.2 kB view details)

Uploaded Aug 30, 2026 Python 3

File details

Details for the file sphinx_gp_opengraph-0.1.0a38.tar.gz.

File metadata

Download URL: sphinx_gp_opengraph-0.1.0a38.tar.gz
Upload date: Aug 30, 2026
Size: 12.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sphinx_gp_opengraph-0.1.0a38.tar.gz
Algorithm	Hash digest
SHA256	`a69da7d69281c1650505c8aa6901f506378869512fb01c886c7c2b1acda99564`
MD5	`e055b284b8966c21efe79b8e43663f57`
BLAKE2b-256	`4c8cbd7463de5c72850ac8f4c5b5870af345b2e232dfda06a1d5eb5f30c9eea3`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sphinx_gp_opengraph-0.1.0a38.tar.gz:

Publisher: release.yml on git-pull/gp-sphinx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sphinx_gp_opengraph-0.1.0a38.tar.gz
- Subject digest: a69da7d69281c1650505c8aa6901f506378869512fb01c886c7c2b1acda99564
- Sigstore transparency entry: 2652734717
- Sigstore integration time: Aug 30, 2026
Source repository:
- Permalink: git-pull/gp-sphinx@a495917a2a867538a6c7c3254ff887d54b27eb7e
- Branch / Tag: refs/tags/v0.1.0a38
- Owner: https://github.com/git-pull
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@a495917a2a867538a6c7c3254ff887d54b27eb7e
- Trigger Event: push