使用作者模式

  • 如何激活作者模式。

虽然 Antora 的主要功能是生成用于发布的站点，但它也可以作为作者的工具。通过配置 Antora 使用本地存储库，您可以预览本地内容，包括您尚未提交的内容。

激活作者模式

当您配置 playbook 使用本地克隆来自一个或多个内容存储库时，作者模式就会被激活。Antora 将使用您本地机器上的存储库，而不是从远程位置克隆它。这种情况假设您已经克隆了一个存储库，并希望将其合并到站点生成中。

首先，在您的项目中创建一个名为 workspace 的文件夹。

$ mkdir workspace

切换到新创建的目录并克隆一个存储库：

$ git clone https://github.com/my-antora-demo/server-docs workspace/server-docs

接下来，为本地使用制作副本的 playbook 文件。在下面的示例中，antora-playbook.yml 被复制，并将新文件命名为 local-antora-playbook.yml。

$ cp antora-playbook.yml local-antora-playbook.yml

接下来，打开您的新 playbook 文件，并配置它使用克隆的存储库，而不是远程存储库。您可以将存储库指定为相对于 playbook 文件的路径或绝对路径。

示例 1. local-antora-playbook.yml 
content:
  sources:
  - url: ./workspace/server-docs
    branches: HEAD (1)
1 在作者模式下，通常希望使用本地存储库当前检出的 HEAD

使用新 playbook 文件构建您的 Antora 站点。

$ antora local-antora-playbook.yml

您的本地存储库的内容将被合并到流水线中。

如果您的 workspace 目录位于 playbook 存储库内部，最好将其添加到您的 .gitignore 文件中，以免将其推送到远程。

使用多个工作树

在前一节中，您了解了如何配置 Antora 使用具有单个工作树的本地存储库。如果您的存储库只有一个内容分支，这种设置非常适合。但是，一旦您开始使用多个分支，使用单个工作树就不太理想了。这意味着每次需要阅读或更新不同组件版本中的文件时都必须切换分支，使得在不同版本之间移动文件非常困难。这就是多个工作树发挥作用的地方。

本地 git 存储库可以支持多个工作树。本地存储库的位置仍然充当主工作树。使用 git worktree 命令，您可以将附加的工作树与存储库关联起来，每个工作树映射到一个离散的分支。新工作树称为 链接工作树。它位于与主工作树分开的目录中。这意味着您可以为单个存储库同时检出多个分支。

Antora 识别附加到本地内容源的链接工作树，前提是您已启用此功能，并且如果它们与 playbook 中指定的分支模式之一匹配，Antora 将使用它们。要启用此功能，请在 Antora playbook 中为内容源的条目添加 worktrees: true。

按照以下步骤设置具有多个工作树的本地内容源：

  1. 克隆 playbook 存储库。

  2. 在 git 为克隆创建的文件夹中，创建一个名为 workspace 的文件夹。

  3. 切换到 workspace 文件夹，并创建另一个文件夹来保存您的内容存储库的工作树（例如，workspace/software-with-docs）（请注意，这不是一个 git 存储库）。

  4. 切换到该文件夹。

  5. 将内容存储库克隆到 main 文件夹（或您的默认分支名称）（例如，git clone https://github.com/my-antora-demo/server-docs main）。

  6. 切换到该文件夹。

  7. 现在为您想要编辑的每个分支创建一个工作树，使用 git worktree。例如：git worktree add ../6.0 6.0。 git worktree add 的第一个参数是工作树的位置，第二个是分支的名称。通常，您将使用分支的名称命名工作树文件夹。

  8. 现在返回到 playbook 存储库（其中位于 antora-playbook.yml）并按照前一节中描述的步骤打开名为 local-antora-playbook.yml 的作者 playbook，如有必要，创建它。

  9. 在 playbook 文件中，将内容存储库的 URL 更改为指向 workspace 内部的克隆存储库（例如，./workspace/software-with-docs/main）。您必须将 Antora 指向主工作树，而不是链接工作树之一。

  10. 在相同的内容源条目中，通过添加 worktrees: true 启用 工作树功能。

对每个要处理的内容存储库重复步骤 3-10。

现在，当 Antora 扫描分支时，它将自动发现您已链接的工作树，并从中读取文件（而不是从 git 树中读取）。通过这种设置，您可以将 playbook 存储库用作您的主基地，并将所有内容存储库和分支组织在其下以进行作者编写。

您可以在 playbook 存储库中创建一个脚本，以自动设置此作者环境的过程。

要了解有关 git 工作树及其如何使用的更多信息，请参阅 git 文档中的 git-worktree 页面。

作者模式操作顺序

当存储库是本地的时，生成器选择哪些分支以及它是否会选择您未提交的更改可能会让您感到困惑。以下是本地存储库的处理方式：

  • 使用您本地机器上的存储库内容，而不是来自远程存储位置的内容。

  • 本地存储库不会从远程存储位置更新；Antora 假定作者将管理存储库（根据需要显式调用 git fetch 或 git pull）。

以下是作者模式下选择分支的方式：

  • 同时考虑本地分支和与远程 url 关联的远程分支。

  • 如果本地分支与远程分支同名，则选择本地分支。

  • 工作树的内容将用于当前分支的文件。除了名称外，当前分支实际上被忽略。

  • 您的工作树的当前分支必须与在 url 条目上配置的 branches 过滤器匹配。如果不匹配，则将忽略工作树。您可以使用 保留的 HEAD 值 来确保始终使用当前工作树。

如果您想使用多个工作树，只需多次克隆存储库并在 playbook 中配置多个条目。您可以使用 branches 键来 过滤掉您不想要的分支名称。