Installation¶

python-mpipinstallsphinxext-opengraph

Thematplotlib package is required to generate social cards:

python-mpipinstallsphinxext-opengraph[social_cards]

Usage¶

Addsphinxext.opengraph to the extensions list inconf.py:

extensions=['sphinxext.opengraph',]

Then set theogp_site_url configuration valueto the public URL for your documentation, e.g.:

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

Options¶

These values are placed in theconf.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 theproject config value.Set toFalse 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.Seethe 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 tothe root of the HTML output as defined byogp_site_url.

ogp_image_alt¶

Type:

str|Literal[False]

Default:

None

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

ogp_use_first_image¶

Type:

bool

Default:

False

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

ogp_type¶

Type:

str

Default:

'website'

This sets the ogp type attribute.For more information on the types available, see athttps://ogp.me/#types.By default, it is set towebsite, 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

WhenTrue, generates<metaname="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 forog:url and the URL text in generated social media preview cards.It is most useful with versioned documentation, where you intendto set the “stable” or “latest” version as the canonical location of each page,similarly torel="canonical".If not set, the option defaults to the value ofogp_site_url.

Example Config¶

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

ogp_site_url="http://example.org/"ogp_image="http://example.org/image.png"ogp_description_length=300ogp_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 pageand set unsupported arbitrary Open Graph tags.

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

:og:description: New description:og:image: http://example.org/image.png:og:image:alt: Example ImagePage contents=============

:og:video: http://example.org/video.mp4Page contents=============