sphinxext-opengraph

Sphinx extension to generate Open Graph metadata for your documentation.

Installation

python -m pip install sphinxext-opengraph

The matplotlib package is required to generate social cards:

python -m pip install sphinxext-opengraph[social_cards]

Usage

Add sphinxext.opengraph to the extensions list in conf.py:

extensions = [
   'sphinxext.opengraph',
]

Then set the ogp_site_url configuration value to the public URL for your documentation, e.g.:

ogp_site_url = 'https://docs.example.org/'

Tip

Documentation hosted on Read The Docs automatically detects the site URL through the READTHEDOCS_CANONICAL_URL environment variable, so no configuration is needed.

Options

These values are placed in the conf.py of your Sphinx project.

ogp_site_url
Type:
str
Default:
''

This config option is important, set it to the URL the site is being hosted on.

ogp_description_length
Type:
int
Default:
200

Configure the number of characters taken from a page.

ogp_site_name
Type:
str | Literal[False]
Default:
project

Name of the site. This is displayed above the title. Defaults to the project config value. Set to False to unset and use no default.

ogp_social_cards
Type:
dict[str, bool | str]
Default:
{}

Configuration for automatically creating social media card PNGs for each page. See the social media cards page for more information.

ogp_image
Type:
str | None
Default:
None

Link to image to show. Note that all relative paths are converted to be relative to the root of the HTML output as defined by ogp_site_url.

ogp_image_alt
Type:
str | Literal[False]
Default:
None

Alt text for image. Defaults to using ogp_site_name or the document’s title as alt text, if available. Set to False to disable alt text.

ogp_use_first_image
Type:
bool
Default:
False

Set to True to use each page’s first image, if available. If set to True but no image is found, Sphinx will use ogp_image instead.

ogp_type
Type:
str
Default:
'website'

This sets the ogp type attribute. For more information on the types available, see at https://ogp.me/#types. By default, it is set to website, which should be fine for most use cases.

ogp_custom_meta_tags
Type:
Sequence[str]
Default:
()

List of custom HTML snippets to insert.

ogp_enable_meta_description
Type:
bool
Default:
True

When True, generates <meta name="description" content="..."> from the page.

ogp_canonical_url
Type:
str
Default:
ogp_site_url

This option can be used to override the “canonical” URL for the page, and is used for og:url and the URL text in generated social media preview cards. It is most useful with versioned documentation, where you intend to set the “stable” or “latest” version as the canonical location of each page, similarly to rel="canonical". If not set, the option defaults to the value of ogp_site_url.

Example Config

Simple Config

ogp_site_url = "http://example.org/"
ogp_image = "http://example.org/image.png"

Advanced Config

ogp_site_url = "http://example.org/"
ogp_image = "http://example.org/image.png"
ogp_description_length = 300
ogp_type = "article"

ogp_custom_meta_tags = [
    '<meta property="og:ignore_canonical" content="true" />',
]

ogp_enable_meta_description = True

Per Page Overrides

Field lists can be used to override certain settings on each page and set unsupported arbitrary Open Graph tags.

Make sure you place the fields at the very start of the document such that Sphinx will pick them up and also won’t build them into the HTML.

Overrides

These are some overrides that can be used on individual pages, you can actually override any tag and field lists will always take priority.

:ogp_description_length:

Configure the amount of characters to grab for the description of the page. If the value isn’t a number it will fall back to ogp_description_length.

:ogp_disable:

Disables generation of Open Graph tags on the page.

:og:description:

Lets you override the description of the page.

:description: or .. meta:: :description:

Sets the <meta name="description" content="..."> description.

:og:title:

Lets you override the title of the page.

:og:type:

Override the type of the page. For the list of available types, see at https://ogp.me/#types.

:og:image:

Set the image for the page.

Note: Relative file paths for images, videos and audio are currently not supported when using field lists. Please use an absolute path instead.

:og:image:alt:

Sets the alt text. Will be ignored if there is no image set.

Example

Remember that the fields must be placed at the very start of the file. You can verify Sphinx has picked up the fields if they aren’t shown in the final HTML file.

:og:description: New description
:og:image: http://example.org/image.png
:og:image:alt: Example Image

Page contents
=============

Arbitrary Tags

Additionally, you can use field lists to add any arbitrary Open Graph tag not supported by the extension. The syntax for arbitrary tags is the same with :og:tag: content.

For example:

:og:video: http://example.org/video.mp4

Page contents
=============

Note: Relative file paths for images, videos and audio are currently not supported when using field lists. Please use an absolute path instead.