多个开始路径

start_paths键

start_paths 键允许您为单个存储库的单个引用指定多个内容源根。换句话说，您可以将多个组件版本、组件或分布式组件（每个组件都有自己的 antora.yml 文件）放入存储库的单个分支中，然后使用相同的内容源条目引用所有这些内容源根。以这种方式组织内容时，此功能有可能极大地减少 playbook 中内容源的冗长性。

与 start_path 键的关系

start_path 键只允许您为特定内容源在 playbook 中指定单个路径。相反，start_paths 键允许您指定多个路径。可以使用通配符、排除、大括号、选择、范围和重复模式来进一步合并多个路径。Antora 将根据模式解析一个或多个固定路径。

start_paths 键与 start_path 键互斥。如果内容源同时存在 start_path 和 start_paths 键，则仅使用 start_paths 键。

与git引用的关系

与单个起始路径一样，每个 git 引用（即分支、标记和工作树）都会搜索起始路径。这意味着每个引用的每个起始路径都必须找到一个组件版本描述符。

通常，在使用多个 start_paths 时，您只会使用单个引用（例如 main ）。如果在此情况下使用多个引用，则假定每个引用共享相同的布局。

使用案例

设计多个启动路径主要是为了适应两个用例：

使用文件夹而不是分支进行版本控制的文档。
单个存储库分支中多个产品的文档(例如，monorepo)。

组件版本作为文件夹

您可以使用 start_paths 将组件的所有版本存储在单个存储库分支中，而不是使用多个分支。虽然您可能会错过某些版本控制系统的优势，但此安排可以使经常同时更新多个文档版本的撰写人更轻松。

在这种情况下，您将为 branches 键提供单个值，并使用 start_paths 键告诉 Antora 在分支的哪些目录中使用作为内容根。如果版本文件夹的命名方式一致，则可以使用模式轻松匹配它们。

以下是使用文件夹存储文档版本的存储库布局示例：

📒 repository
  📂 docs
    📂 v1.0
      📄 antora.yml
    📂 v1.1
      📄 antora.yml
    📂 v2.0
      📄 antora.yml

组件作为文件夹

你可以更进一步，使用文件夹而不是使用多个存储库，在单个存储库分支中存储所有组件。如果这些组件有版本，你可能会使用子文件夹来存储版本。如果所有文档由同一个团队或个人维护，并且 Git 的分布式性质只会妨碍工作，那么这种安排效果最好。它也可能用于单体库，在其中存储多个产品的源代码在同一个存储库中。Antora 可以在该结构中的任何地方发现文档。

在这种情况下，你再次为分支键提供单个值，并使用 start_paths 键告诉 Antora 使用分支中的哪些目录作为内容根。但是这一次，内容源根将匹配不同的组件（可能还有版本），而不仅仅是单个组件的版本。

以下是使用文件夹存储组件的存储库布局示例：

📒 repository
  📂 product-a
    📂 docs
      📄 antora.yml
  📂 product-b
    📂 docs
      📄 antora.yml
  📂 product-c
    📂 docs
      📄 antora.yml

当然，存储库可能有许多不属于文档的其他文件和文件夹。

精确路径

如果只有几个路径要注册，您可能会发现使用精确路径模式是合适的。

Example 1. Example 1. antora-playbook.yml

content:
  sources:
  - url: https://github.com/org/repo1
    start_paths: docs (1)
  - url: https://github.com/org/repo2
    start_paths: docs, more-docs (2)
  - url: https://github.com/org/repo3
    start_paths: [docs, more-docs] (3)
  - url: https://github.com/org/repo4
    start_paths:
    - docs (4)
    - more-docs

1	单个路径(相当于使用 `start_path` )。
2	精确路径值的逗号分隔列表。
3	单行数组，用方括号(`[]`)分隔
4	由多行组成的数组，每行用前导 `-` 分隔。

path globbing

除了在 Exact paths 中描述的方法之外，您还可以使用许多(但不是全部) 基本和高级路径 globbing 特性来实现模式匹配。支持通配符、大括号和反式模式的多种组合。Antora 使用这些 glob 模式来解析读取内容的确切路径。

Globbing限制

Antora 实现路径 globbing 的方式对所有支持的基本和高级 globbing 规则都有以下限制：

表达式中的通配符仅匹配目录，而不是文件。例如，不支持类似 product-a/docs/*/index.adoc 的表达式。
花括号表达式必须至少有两个条目，即使存在通配符也是如此。例如，docs/product-{a*,b} 被识别为一个花括号表达式，但 docs/product-{a*} 不会被识别。
在包含通配符的段后面跟随的单个花括号表达式，如果匹配多个字符，则无法工作。例如，*/v{0..99} 可以匹配开始路径 product-a/v2 ，但不能匹配 product-a/v99。而是为每个长度排列使用嵌套花括号表达式，例如 */v{{1..9},{1..9}{0..9}} 。
不支持双重 globstar 模式 **/docs 。Glob 只匹配层次结构中的单个级别。

通配符

通配符匹配可以减少你需要分配给 start_paths 键的值的数量。例如，如果你在一个分支中存储了多个组件，你可以像示例2中所示的逗号分隔列表中列出它们所有。

Example 2. Example 2. antora-playbook.yml

content:
  sources:
  - url: https://github.com/org/repo1
    branches: main
    start_paths: docs/product-a, docs/product-b, docs/product-c

或者，如示例3所示，您可以使用通配符段并减少需要声明的值的数量。

Example 3. Example 3. antora-playbook.yml

content:
  sources:
  - url: https://github.com/org/repo1
    branches: main
    start_paths: docs/product-*

通配符匹配提供了在添加新内容源根时注册它们的可能性，从而保证了模式的一致性。

花括号

花括号表达式可以指定由逗号分隔开的项的显式列表以进行扩展(docs/product-{a,b,c,f})，也可以指定要扩展的项的范围(docs/product-{a..f})。包含单个项，甚至该项包含通配符都不是花括号表达式（例如，docs/product-{a} 和 docs/product-{a*} 不是花括号表达式）。

花括号表达式可以嵌套(例如，docs-*/v{{1..9},{1..9}{0..9} 可以匹配名称为 docs-* 的根文件夹下的 v1 到 v99 子文件夹)。在这种情况下，将测试每个嵌套的花括号表达式的每个排列。

如果在 start_paths 值中使用花括号，则在展开时花括号内的所有条目都必须存在（除非该段前面有一段通配符段）。

如果将 docs/product-{a,b} 指定为 start_paths 值，则以下路径必须在存储库中存在：

docs/product-a
docs/product-b

您可以在文件路径中使用大括号表达式前的前缀，以简化 Antora 在表达式中检查的内容。

Example 4. Example 4. antora-playbook.yml

content:
  sources:
  - url: https://github.com/org/repo1
    branches: main
    start_paths: docs/v{1..9}

还可以在大括号表达式中使用通配符来帮助展开值。

Example 5. Example 5. antora-playbook.yml

content:
  sources:
  - url: https://github.com/org/repo1
    branches: main
    start_paths: docs/product-v{1*,2*}

示例5中的 start_path 模式将匹配以下路径：

docs/product-v1.1
docs/product-v1.2
docs/product-v1.2.1
docs/product-v2.0
docs/product-v2.1.1

否定 globs

使用否定模式来排除先前匹配的模式。如果您希望匹配除匹配特定模式之外的所有目录，则此方法非常有用。

Example 6. Example 6. antora-playbook.yml

content:
  sources:
  - url: https://github.com/org/repo1
    start_paths:
    - docs/user/*
    - docs/dev/*
    - !**/*-beta.* (1)

1	否定的路径 globing 模式必须遵循任何路径包含，并且必须在已经匹配的位置之后声明。

忽略目录

默认情况下，忽略以点开始的目录（即以 . 开头的目录）。要将它们包含在 start_paths 路径 globbing 模式中，请在模式中使用 .* 。例如，使用 docs/.*-{a,b} 来包含所有后缀为 -a 或 -b 的隐藏目录。

可选匹配

在通配符段后面跟随的非通配符段被认为是可选的。这个例外旨在简化目录匹配逻辑。

例如，docs/product-*/client 会匹配 product-a/client ，但如果 product-b 不包含 client 文件夹，则会忽略它。

另一个有效的示例是 docs/product/*/client，其中 * 表示 client 文档的不同版本目录(v1.0、v1.1 等)。如果在某个版本目录中不存在 client 文件夹，则 Antora 会忽略该文件夹。

如果文件路径模式的最后一段包含未匹配的花括号模式，则从验证的角度来看，Antora 会将其视为可选的。

例如，docs/product-*/{client,b2b} 如果 docs/product-a/b2b 不存在，则不会因此未通过验证。