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.