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 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. 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 toFalse
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 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 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 torel="canonical"
. If not set, the option defaults to the value ofogp_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
=============