sphinxext-opengraph#

构建 代码风格：黑色

Sphinx 插件，用于生成 Sphinx 文档的 Open Graph 元数据。

安装#

python -m pip install sphinxext-opengraph

用法#

仅仅需要在 conf.py 中添加 sphinxext.opengraph 到插件列表中。

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

  • ogp_image

    • 这个不是必需的。要显示的图像的链接。请注意，所有相对路径都被转换为相对于 html 输出的根目录，由 ogp_site_url 配置。

  • ogp_image_alt

    • 这个不是必需的。图像的替代文本。默认值为使用 ogp_site_name 或文档的标题作为替代文本（如果可用）。如果要完全关闭替代文本，请将其设置为 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:

    • 设置图像的替代文本。如果没有设置图像，则将被忽略。

示例#

记住，字段 必须 放在文件的开头。您可以验证 Sphinx 是否已拾取字段，如果它们没有显示在最终的 html 文件中。

: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
=============