sphinxext-opengraph

Sphinx扩展，用于为您的文档中的每一页生成 Open Graph元数据。

安装

python -m pip install sphinxext-opengraph

使用

只需将 sphinxext.opengraph 添加到您的 conf.py 中的扩展列表。

extensions = [
   "sphinxext.opengraph",
]

选项

这些值放置在您的Sphinx项目的 conf.py 中。

在Read The Docs上托管文档的用户 不需要 设置以下任何内容，除非需要自定义配置。扩展将自动检索您的站点URL。

• ogp_site_url
  • 此配置选项非常重要，将其设置为网站托管所在的URL。
• ogp_description_length
  • 配置从页面中取出的字符数量。默认值200对大多数人来说可能很好。如果使用的是除数字以外的其他内容，则默认回退到200。
• ogp_site_name
  • 此选项不是必需的。网站名称。此名称显示在标题上方。默认值为 Sphinx 的 project 配置值。设置为 False 以取消设置并使用默认值。
• ogp_social_cards
  • 为每个页面自动创建社交媒体卡片 PNG 的配置。有关更多信息，请参阅 社交媒体卡片文档。
• ogp_image
  • 此选项不是必需的。显示的图片链接。注意，所有相对路径都将转换为相对于由 ogp_site_url 定义的 html 输出根目录。
• ogp_image_alt
  • 此选项不是必需的。图片的 alt 文本。默认使用 ogp_site_name 或文档的标题作为 alt 文本，如果可用。如果您想完全关闭 alt 文本，请设置为 False。
• ogp_use_first_image
  • 此选项不是必需的。如果设置为 True 并有可用图片，则使用每个页面的第一张图片。如果设置为 True 但找不到图片，Sphinx 将使用 ogp_image。
• ogp_type
  • 此选项设置 ogp 类型属性，有关可用类型的更多信息，请参阅 https://ogp.me/#types。默认设置为 website，这应该适用于大多数用例。
• ogp_custom_meta_tags
  • 此选项不是必需的。插入自定义 html 片段的列表。
• ogp_enable_meta_description
  • 此选项不是必需的。当设置为 True 时，从页面生成 <meta name="description" content="...">。

示例配置

简单配置

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 = 300
ogp_type = "article"

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

ogp_enable_meta_description = True

每页覆盖

字段列表 用于允许您覆盖每个页面上的某些设置并设置不受支持的任意 Open Graph 标签。

确保您将字段放置在文档的非常开始处，以便 Sphinx 可以将其拾取，并且不会将其构建到 html 中。

覆盖

以下是一些可以在单个页面上使用的覆盖选项，您实际上可以覆盖任何标签，字段列表始终具有优先权。

• :ogp_description_length
  • 配置获取页面描述的字符数。如果值不是数字，则回退到 ogp_description_length。[^1]
• :ogp_disable
  • 在页面上禁用 Open Graph 标签的生成。[^1]
• :og:description
  • 允许您覆盖页面的描述。
• :description: 或 .. meta::\n :description:
  • 设置 <meta name="description" content="..."> 描述。
• :og:title
  • 允许您覆盖页面的标题。
• :og:type
  • 覆盖页面的类型，有关可用类型的列表，请参阅 https://ogp.me/#types。
• :og:image
  • 设置页面的图片。[^2]
• :og:image:alt
  • 设置 alt 文本。如果没有设置图片，将忽略。

示例

请记住，字段 必须 放置在文件的非常开始处。如果它们没有显示在最终的 html 文件中，您可以通过它们来验证 Sphinx 是否已拾取字段。

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

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

任意标签[^2]

此外，您还可以使用字段列表添加任何不受扩展支持的任意 Open Graph 标签。任意标签的语法与 :og:tag: content 相同。例如

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

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

[^1]: 注意略有不同的语法，因为这不是一个直接的开源图形标签。[^2]: 注意：使用字段列表时，图片、视频和音频的相对文件路径目前 不支持。请使用绝对路径。