URLs for Content Sources

url键

Antora可以连接到公共和私有的git存储库，这些存储库在playbook中的url键中定义。在sources键下必须指定至少一个url键。您可以根据需要添加尽可能多的url键。每个url键告诉Antora在哪里找到包含内容源文件的git存储库。

示例1. antora-playbook.yml

content:
  sources:
  - url: https://git-service.com/org/repo.git
  - url: /absolute/path/to/local-repo

url键接受git支持的任何URI，包括本地文件系统路径。

与git一样，Antora根据值中的某些字符区分本地文件系统路径和远程URI。如果值符合以下两条规则中的任一条，该值将始终被处理为远程URI，而不是本地文件系统路径。

该值包含一个冒号，后面不跟斜杠或反斜杠（host:repo）。
该值包含一个冒号，后面跟着两个斜杠（://）。

使用远程内容存储库

所有远程内容存储库必须通过URL（使用基本或加密的HTTP协议获取的Web地址）访问（即http://或https://）。存储库位置可以使用URL、SSH URI或git URI表示。在内部，该位置始终转换为URL。

content:
  sources:
  - url: https://git-service.com/org/repo-z.git
  - url: git@git-service.com:org/repo-y.git
  - url: git://git-service.com/org/repo-x.git

是否需要.git扩展名取决于git主机的设置。对于托管在GitHub上的存储库，不需要，对于托管在GitLab上的存储库，需要，对于托管在Team Foundation Server（TFS）或Azure DevOps上的存储库，禁止，举几种情况（并展示问题的性质）。这就是为什么为您提供了ensure_git_suffix键，它默认启用。

只要为私有内容源存储库指定了支持的身份验证方法，Antora就可以连接到私有git存储库。

使用本地内容存储库

Antora允许url的值是指向至少有一个提交的本地存储库的相对或绝对文件系统路径。

content:
  sources:
  - url: /absolute/path/to/local-repo (1)
  - url: https://git-service.com/org/repo-z.git
  - url: ./another-local-repo (2)

1	指向git存储库的绝对路径
2	指向git存储库的相对路径（从playbook所在目录开始）

为了使用本地内容存储库与Antora，即使使用工作树（HEAD），存储库必须至少有一个提交。如果您还没有准备好提交任何文件，可以初始化存储库并创建一个空提交（例如，git init . && git commit --allow-empty -m init）。

相对路径将根据以下规则扩展为绝对路径：

如果第一个路径段是波浪号（~），则剩余路径相对于用户的主目录解析。
如果第一个路径段是点（.），则剩余路径相对于playbook文件的位置解析。
如果第一个路径段是紧接着加号的波浪号（~+），或者不以前述前缀开头，则剩余路径相对于当前工作目录解析。

使用git工作树

当内容源的URL是一个本地存储库（必须至少有一个提交），并且branches过滤器匹配当前检出的分支（即工作树分支），Antora会从工作树（即本地文件系统上的工作目录）读取文件，而不是从git索引中读取。这种行为是Antora中的作者模式的核心。这意味着您不必在本地提交文件之后Antora才能使用它们。

示例2. 使用工作树中的文件

content:
  sources:
  - url: ./demo-component-b
    branches: main
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0

您可以使用符号名称HEAD作为当前分支名称的别名，而不是明确指定当前分支的名称。这样可以避免在切换分支时更新playbook的麻烦。

示例3. 使用工作树中的文件

content:
  sources:
  - url: ./demo-component-b
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0

如果分支过滤器同时匹配工作树分支和另一个包含相同文件的分支的情况，Antora将无法运行，因为它不允许重复文件。

绕过git工作树

为了确保Antora不使用工作树中的文件，即使分支过滤器匹配工作树分支，您可以直接将URL指向.git目录。这样可以有效地隐藏工作树，使Antora不会使用它。

示例4. 直接引用.git文件夹以绕过工作树中的文件

content:
  sources:
  - url: ./demo-component-b/.git
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0

worktrees键设置为 false。

示例5. 将worktrees设置为false以绕过工作树中的文件

content:
  sources:
  - url: ./demo-component-b
    branches: HEAD
    worktrees: false
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0

请记住，在这种情况下，所有文件必须在本地提交，Antora才能使用它们。