Edit URL :: Antora Docs

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

示例1. edit_url键和值

edit_url: '{web_url}/blob/{refname}/{path}' (1)

1	当`edit_url`的值以大括号（`{`）开头时，将`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。如果您使用与Antora计算的Web URL不同的Web URL，则可以省略此占位符。
refname: {refname}是git引用的名称（例如，v2.1.x、main、rawhide）。
reftype: {reftype}是git引用的类型（即标签或分支）。
refhash: {refhash}是git引用的提交哈希（例如，aab0e5684afe0d4e05955fbef72b6e5538bb1ec5）。
path: {path}是源文件相对于存储库根目录的路径。如果指定了start_path，则包括它。

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

示例2. edit_url占位符

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文件存储在zap存储库的v1.2.5分支中，位于ROOT模块的pages目录中。使用示例2中分配给edit_url的模式，Antora将为index.adoc计算出示例3中显示的编辑URL。

示例3. 使用示例2中的输入为index.adoc生成的编辑URL

https://app.company.com/the-group/zap/_src/v1.2.5/u890/modules/ROOT/pages/index.adoc

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

当内容源有一个指定的start_path时，Antora会将其添加到{path}之前。

示例4. 带有start_path和edit_url设置的内容源

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将是：

示例5. 使用示例4中的输入为index.adoc生成的编辑URL

https://app.company.com/the-group/zap/_src/v1.2.5/u890/learn/docs/modules/ROOT/pages/index.adoc

将相同的edit_url应用于多个内容源

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

示例6. 在content键上设置edit_url

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`直接设置在`content`键上时，就像这里一样，其值将应用于所有内容源，除非在单个内容源上重置或禁用该键。

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

示例7. 在content键和单个源上设置edit_url

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	此内容源将继承直接在`content`键上设置的`edit_url`键的值。
3	当在单个内容源上设置`edit_url`时，该值将被使用，而不是分配给`content`键上设置的`edit_url`键的值。
4	此内容源将继承直接在`content`键上设置的`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。

示例8. 将编辑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上对应源文件的渲染视图。

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

禁用编辑URL

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

edit_url键可以关闭所有内容源或每个单独内容源上的编辑URL功能。要禁用编辑URL，请将波浪符（~）或单词false分配给edit_url键。

content:
  branches: v*
  edit_url: ~ (1)
  sources:
  - url: https://app.company.com/the-group/zap.git
  - url: https://gitlab.com/cave/sneaky.git

1	通过在`content`键上设置`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`未明确设置在`content`键上或此内容源上，因此将使用内置在Antora中的默认编辑URL行为。

将内容源恢复为默认的编辑URL行为

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

示例9. 将edit_url重置为默认行为

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`直接设置在`content`键上时，其值将应用于所有内容源，除非在单个内容源上重置或禁用该键。
2	将值`true`分配给`edit_url`键，以将内容源恢复为内置在Antora中的默认编辑URL行为。

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