`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.

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