修改URL

在此页面上，您将了解：

  • Antora 如何为每个页面构建编辑 URL。

  • 如何自定义编辑 URL。

  • 如何禁用编辑 URL。

Antora 的默认编辑 URL 分配

Antora 会自动为源自托管 GitLab (gitlab.com)、GitHub (github.com)、Bitbucket (bitbucket.org) 和 Pagure (pagure.io) 服务 (SAAS) 的所有文件生成编辑 URL。为此，它首先将内容源 URL 转换为 Web URL，然后使用当前文件的引用和路径信息构建托管存储库中该文件的编辑模式的 URL。

在默认 UI 中，Antora 使用此值（如果设置）在每个页面的右上角创建“编辑此页面”链接。该链接将访问者引导至托管 git 服务提供的该文件的编辑界面。例如，如果您单击此页面上的编辑此页面链接，您的浏览器将转到 GitLab 的文件编辑界面（位于 gitlab.com 上）并加载用于创建此页面的 AsciiDoc 源。

一个例外是存储库是私有的。在这种情况下，默认 UI 不会显示“编辑此页面”链接。但是，您可以在构建网站时通过设置 FORCE_SHOW_EDIT_PAGE_LINK 环境变量（例如 FORCE_SHOW_EDIT_PAGE_LINK=true）来强制默认 UI 显示链接。或者，您可以自定义 UI 模板来更改逻辑。

另一个例外是页面是否源自本地文件系统（即工作树）。在这种情况下，默认 UI 使用本地 file:// URI 作为“编辑此页面”链接。您可以在构建站点时通过设置 CI 环境变量（例如 CI=true）来强制默认 UI 始终使用编辑 URL。（大多数 CI 环境中已设置此环境变量）。假设如果设置了 CI 环境变量，则站点将发布到无法访问 file://URI 的远程服务器。您可以自定义 UI 模板来更改逻辑，而不是设置此环境变量。

这涵盖了如何使用编辑 URL。现在让我们看看如何自定义该值。

自定义编辑 URL

当您使用无法识别的 git 解决方案，或者您希望编辑此页面链接到页面源文件的备用视图（例如原始或渲染显示）时，edit_url 键非常有用。

edit_url 键在 playbook 中设置，可以应用于所有内容源或针对每个单独的源进行自定义。该键接受一个 URL 模式，其中包含 git 解决方案或源文件视图的 URL 段以及几个占位符段：{web_url}、{refname}、{reftype}、{refhash} 和 {path}。Antora 在处理时自动使用文件的原始信息填充这些占位符。

edit_url: '{web_url}/blob/{refname}/{path}' (1)
1 当 edit_url 的值以大括号 ({) 开头时，请将其括在单引号 (') 中。

示例 1 显示了一个假设的包含多个占位符的编辑 URL 模式。blob 一词是不由占位符表示的 URL 段的示例。在下一节中，我们将解释这些占位符的作用。

Antora 如何组装页面的编辑 URL？

当 edit_url 设置时，无论是默认还是显式设置，Antora 都会根据每个页面的内容源和文件来源信息来计算每个页面的 {web_url}、{refname}、{reftype}、{refhash} 和 {path} 占位符的值。然后，使用分配给 edit_url 键的模式，组合每个页面的唯一编辑 URL。

web_url

{web_url} 占位符是 Antora 根据其 git URL 自动计算的内容源存储库的相应 Web URL。例如，https://gitlab.com/cave/sneaky.git 会转换为 https://gitlab.com/cave/sneaky。如果您使用的 Web URL 与 Antora 计算的 URL 不同，则可以省略此占位符。

refname

{refname} 是 git 引用的名称（例如 v2.1.x、main、rawhide）。

reftype

{reftype} 是 git 引用的类型（即标签或分支）。

refhash

{refhash} 是 git 引用的提交哈希（例如，aab0e5684afe0d4e05955fbef72b6e5538bb1ec5）。

path

{path} 是源文件相对于存储库根目录的路径。如果指定了，它包括 start_path。

要查看 Antora 为占位符计算的值的示例，我们将使用示例 2 中所示的内容源、分支和编辑 URL 模式输入。

Example 1. Example 2. edit_url placeholders
content:
  sources:
  - url: https://app.company.com/the-group/zap.git
    branches: v1.2.5, next
    edit_url: '{web_url}/_src/{refname}/u890/{path}'

让我们确定从名为 index.adoc 的文件生成的页面的编辑 URL 是什么样子。该 index.adoc 文件存储在 ROOT 模块的 pages 目录中的 zap 存储库的分支 v1.2.5 中。使用示例 2 中分配给 edit_url 的模式，Antora 将计算示例 3 中所示的 index.adoc 的编辑 URL。

Example 2. Example 3. Edit URL for index.adoc using the inputs from Example 2
https://app.company.com/the-group/zap/_src/v1.2.5/u890/modules/ROOT/pages/index.adoc

Antora 将 {web_url} 替换为内容源的 Web URL。在这种情况下，.git 将从 url 值的末尾删除。 {refname} 替换为 v1.2.5 git 分支引用。最后，{path} 被替换为源文件的路径（相对于存储库的根目录）。由于该源没有指定的起始路径，因此生成的路径为 modules/ROOT/pages/index.adoc。

当内容源分配有 start_path 时，Antora 会将其添加到 {path} 之前。

Example 3. Example 4. Content source with start_path and edit_url set
content:
  sources:
  - url: https://app.company.com/the-group/zap.git
    branches: v1.2.5, next
    start_path: learn/docs
    edit_url: '{web_url}/_src/{refname}/u890/{path}'

使用示例 4 中的输入，index.adoc 的编辑 URL 将为：

Example 4. Example 5. Edit URL for index.adoc using the inputs from Example 4
https://app.company.com/the-group/zap/_src/v1.2.5/u890/learn/docs/modules/ROOT/pages/index.adoc

对多个内容源应用相同的 edit_url

当您的所有或大部分内容源使用相同的 edit_url 时，您可以直接在内容键上设置它。

Example 5. Example 6. Set edit_url on the content key
content:
  edit_url: '{web_url}/_src/{refname}/u890/{path}' (1)
  sources:
  - url: https://app.company.com/the-group/zap.git
    branches: v1.2.5, next
  - url: https://app.company.com/city/team-l/zonk.git
    branches: v2.*
1 当直接在内容键上设置 edit_url 时（如此处所示），其值将应用于所有内容源，除非在单个内容源上重置或禁用该键。

如示例 7 所示，即使在内容键上设置了 edit_url 键，也可以在单个内容源上设置它。

Example 6. Example 7. Set edit_url on the content key and an individual source
content:
  edit_url: '{web_url}/_src/{refname}/u890/{path}' (1)
  sources:
  - url: https://app.company.com/the-group/zap.git (2)
    branches: v1.2.5, next
  - url: https://git.secretbase.org/ack/boom
    branches: dev
    edit_url: '{web_url}/{refname}/ping/0/{path}' (3)
  - url: https://app.company.com/city/team-l/zonk.git (4)
    branches: v2.*
1 这个 edit_url 键直接设置在 content 键上。除非在单个内容源上重置或禁用该密钥，否则其值将应用于所有内容源。
2 该内容源将继承直接在内容键上设置的 edit_url 键的值。
3 当在单个内容源上设置 edit_url 时，将使用该值而不是分配给内容键上设置的 edit_url 键的值。
4 该内容源将继承直接在内容键上设置的 edit_url 键的值。

更改链接的源文件视图以编辑此页面

默认情况下，页面的编辑 URL 链接到托管存储库的 git 服务的文件编辑界面。 只要内容源存储在 Antora 识别的托管 git 服务之一（包括 GitLab (gitlab.com)、GitHub (github.com)、Bitbucket (bitbucket.org) 和 Pagure (pagure.io)）中，此操作就有效）。如果存储库未存储在这些托管服务之一（例如，自托管的 GitLab 或 BitBucket 实例）中，您可以使用 edit_url 键来配置此 URL 的构造方式。例如，在示例 8 中，每个页面的计算编辑 URL 现在将是相应源文件的 GitLab 渲染文件视图的 URL。

content:
  edit_url: '{web_url}/blob/{refname}/{path}' (1)
  sources:
  - url: https://gitlab.com/cave/sneaky.git
    branches: v2.0, v1.0
1 edit_url 键分配了 GitLab 渲染文件视图的 URL 模式。

使用示例 8 中的输入，源自 https://gitlab.com/cave/sneaky.git 存储库的每个页面上的“编辑此页面”链接将链接到 GitLab 上相应源文件的渲染视图。

要更改编辑此页面的链接文本或将其替换为图像，您需要更新 UI。

关闭编辑URL

如果存储库是私有的，则默认 UI 将不会显示当前页面的“编辑此页面”链接，即使定义了编辑 URL。但是，如果存储库是公共的，并且您想要禁用该链接，或出于任何其他原因使编辑 URL 无效，则可以使用 playbook 来执行此操作。

edit_url 键可以关闭所有内容源或每个内容源的编辑 URL 功能。要禁用编辑 URL，请为 edit_url 键指定波浪号 (~) 或单词 false。

content:
  branches: v*
  edit_url: ~ (1)
  sources:
  - url: https://app.company.com/the-group/zap.git
  - url: https://gitlab.com/cave/sneaky.git
1 通过在内容键上设置 edit_url 并为其分配值 ~，禁用所有内容源的编辑 URL 功能。波形符 (~) 禁用编辑 URL 功能。除非为每个内容源重置 edit_url，否则不会为源自内容源的任何页面生成编辑 URL。

还可以在单个内容源上禁用 edit_url。

content:
  branches: v*
  sources:
  - url: https://app.company.com/the-group/zap.git
    edit_url: ~ (1)
  - url: https://gitlab.com/cave/sneaky.git (2)
1 edit_url 键在此单独的内容源上设置并分配了值 ~。
2 由于 edit_url 未在内容键或此内容源上显式设置，因此它将使用 Antora 中内置的默认编辑 URL 行为。

将内容源还原为默认的编辑 URL 行为

即使您在内容键级别设置或禁用了 edit_url 键，您也可以恢复为单个内容源的默认编辑 URL 行为。在源上，设置 edit_url 并将其指定为 true 值。

Example 7. Example 9. Reset edit_url to the default behavior
content:
  branches: v*
  edit_url: '{web_url}/_src/{refname}/u890/{path}' (1)
  sources:
  - url: https://app.company.com/the-group/zap.git
  - url: https://gitlab.com/cave/sneaky.git
    edit_url: true (2)
  - url: https://app.company.com/city/team-l/zonk.git
1 当直接在内容键上设置 edit_url 时，其值将应用于所有内容源，除非在单个内容源上重置或禁用该键。
2 将值 true 分配给 edit_url 键可将内容源恢复为默认编辑 URL 行为。

在示例 9 中，zap 和 zonk 内容源将使用内容键上设置的 edit_url，而偷偷摸摸的源将使用 Antora 内置的默认编辑 URL 行为。