GitHub Expand
logo Sphinx

Navigation

  • Documentation »
  • Using Sphinx »
  • 插件 »
  • sphinx.ext.extlinks -- 缩短外部链接的标记

On this page

  • sphinx.ext.extlinks -- 缩短外部链接的标记
    • extlinks
    • extlinks_detect_hardcoded_links

The Basics

  • Installing Sphinx
  • Getting started
  • Build your first project

User guide

  • Using Sphinx
    • reStructuredText
    • Markdown
    • Cross-references
    • 配置
    • Builders
    • Domains
    • 插件
      • sphinx.ext.autodoc -- Include documentation from docstrings
      • sphinx.ext.autosectionlabel -- 允许通过标题引用章节
      • sphinx.ext.autosummary -- Generate autodoc summaries
      • sphinx.ext.coverage -- Collect doc coverage stats
      • sphinx.ext.doctest -- Test snippets in the documentation
      • sphinx.ext.duration -- Measure durations of Sphinx processing
      • sphinx.ext.extlinks -- 缩短外部链接的标记
      • sphinx.ext.githubpages -- 在 GitHub Pages 上发布 HTML 文档
      • sphinx.ext.graphviz -- 在文档中嵌入 Graphviz 图
      • sphinx.ext.ifconfig -- Include content based on configuration
      • sphinx.ext.imgconverter -- A reference image converter using Imagemagick
      • sphinx.ext.inheritance_diagram -- Include inheritance diagrams
      • sphinx.ext.intersphinx -- 链接到其他项目的文档
      • sphinx.ext.linkcode -- 添加到源代码的外部链接
      • Math support for HTML outputs in Sphinx
      • sphinx.ext.napoleon -- 支持 NumPy 和 Google 风格的文档字符串
      • sphinx.ext.todo -- Support for todo items
      • sphinx.ext.viewcode -- 添加到高亮源代码的链接
    • HTML theming
    • 国际化
    • Sphinx Web Support
  • Extending Sphinx
  • Sphinx API
  • LaTeX customization

Community

  • Get support
  • Contribute to Sphinx
  • Sphinx FAQ
  • Sphinx authors

Reference

  • Command-line tools
  • 配置
  • 插件
    • sphinx.ext.autodoc -- Include documentation from docstrings
    • sphinx.ext.autosectionlabel -- 允许通过标题引用章节
    • sphinx.ext.autosummary -- Generate autodoc summaries
    • sphinx.ext.coverage -- Collect doc coverage stats
    • sphinx.ext.doctest -- Test snippets in the documentation
    • sphinx.ext.duration -- Measure durations of Sphinx processing
    • sphinx.ext.extlinks -- 缩短外部链接的标记
    • sphinx.ext.githubpages -- 在 GitHub Pages 上发布 HTML 文档
    • sphinx.ext.graphviz -- 在文档中嵌入 Graphviz 图
    • sphinx.ext.ifconfig -- Include content based on configuration
    • sphinx.ext.imgconverter -- A reference image converter using Imagemagick
    • sphinx.ext.inheritance_diagram -- Include inheritance diagrams
    • sphinx.ext.intersphinx -- 链接到其他项目的文档
    • sphinx.ext.linkcode -- 添加到源代码的外部链接
    • Math support for HTML outputs in Sphinx
    • sphinx.ext.napoleon -- 支持 NumPy 和 Google 风格的文档字符串
    • sphinx.ext.todo -- Support for todo items
    • sphinx.ext.viewcode -- 添加到高亮源代码的链接
  • reStructuredText
  • 术语表
  • Changelog
  • Projects using Sphinx

sphinx.ext.extlinks -- 缩短外部链接的标记¶

Module author: Georg Brandl

Added in version 1.0.

此插件旨在帮助处理常见模式,即有许多指向同一站点上的 URL 的外部链接,例如指向 bug 跟踪器、版本控制 Web 界面或其他网站中的子页面的链接。它通过提供基本 URL 的别名来实现,因此在创建链接时只需要提供子页面名称。

假设您想在 Sphinx 跟踪器上包含许多指向问题的链接,位于 https://github.com/sphinx-doc/sphinx/issues/num 上。一遍又一遍地输入此 URL 是乏味的,因此您可以使用 extlinks 来避免重复。

此插件添加了配置值:

extlinks¶

此配置值必须是外部站点的字典,将唯一的短别名映射到 基本 URL 和 标题。例如,要为上述问题创建别名,您可以添加:

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue %s')}

现在,您可以使用别名作为新角色,例如 :issue:`123`。这将插入到 https://github.com/sphinx-doc/sphinx/issues/123 的链接。如您所见,角色中给定的目标在 基本 URL 中替换了 %s。

链接标题取决于元组中的第二项,即 caption:

  • 如果 caption 为 None,则链接标题为完整 URL。

  • 如果 caption 是字符串,则它必须包含 %s 一次。在这种情况下,链接标题是 caption,其中部分 URL 替换为 %s -- 在上面的示例中,链接标题将是 issue 123。

要在 基本 URL 或 caption 中生成文字 %,请使用 %%:

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
                      '[K&R; page %s]')}

您还可以使用其他生成链接的角色支持的常规“显式标题”语法,即 :issue:`this issue <123>。

Changed in version 4.0: 支持在标题中用 '%s' 替换。

Note

由于链接是从读取阶段的角色生成的,因此它们显示为普通链接,例如 linkcheck 构建器。

extlinks_detect_hardcoded_links¶

如果启用,extlinks 会发出警告,如果可以通过 extlink 替换硬编码链接,则会发出警告并建议替换。默认为 False。

Added in version 4.5.

Previous
sphinx.ext.duration -- Measure durations of Sphinx processing
Next
sphinx.ext.githubpages -- 在 GitHub Pages 上发布 HTML 文档
© Copyright 2007-2025, the Sphinx developers. Created using Sphinx 8.2.0+/f0279b6.