安装和运行 Antora 快速入门

本快速入门将引导您完成安装 Antora 并生成您的第一个文档站点所需的初始步骤。

在本页面上，您将学到：

  • 如何安装 Node.js。

  • 如何安装 Antora。

  • 如何创建您的第一个 Antora playbook。

  • 如何运行 Antora 以生成基于 playbook 的站点。

安装 Node.js

Antora 需要一个活跃的长期支持（LTS）版本的 Node.js。要查看您是否已安装 Node.js 以及其版本，请打开终端并键入：

$ node -v

此命令应返回一个活跃的 Node.js LTS 版本号，例如：

$ node --version
v16.20.2

如果您的计算机上有一个活跃的 Node.js LTS 版本，则可以准备好安装 Antora。

如果在您的终端中没有显示版本号，则需要安装 Node.js。我们建议使用 nvm 安装 Node.js，但您也可以选择其他方法。请参考以下指南之一，了解如何在您的平台上安装 nvm 和 Node.js。

如果您已安装 Node.js，但它不是活跃的 LTS 版本，则需要升级 Node.js。要升级到最新的 Node.js LTS 版本并将其设置为默认版本，请在终端中键入以下命令：

Linux 和 macOS 
$ nvm install --lts
$ nvm alias default 16
Windows 
$ nvm install 16.20.2
$ nvm alias default 16.20.2

安装完 Node.js 后，现在是时候安装 Antora 了。

安装 Antora

要使用 Antora 生成文档站点，您需要 Antora 命令行界面（CLI）和 Antora 站点生成器。要安装 Antora，请首先创建一个名为 docs-site 的新目录，并切换到该目录。

$ mkdir docs-site && cd docs-site

接下来，让我们在 playbook 项目中安装所需的软件包，以便您可以使用 npx 运行 antora 命令。

$ node -e "fs.writeFileSync('package.json', '{}')"
$ npm i -D -E @antora/cli@3.1 @antora/site-generator@3.1

通过运行以下命令验证 antora 命令现在可用：

$ npx antora -v

如果安装成功，该命令将报告您指定的 Antora CLI 和站点生成器软件包的版本。

$ npx antora -v
@antora/cli: 3.1.7
@antora/site-generator: 3.1.7

这些版本也可以在 package.json 中找到，您可以使用它来升级 Antora。

您可以选择在全局范围内安装 Antora，以便在您的 PATH 上可用 antora 命令。要这样做，请将 -g 选项传递给 npm i。

$ npm i -g @antora/cli@3.1 @antora/site-generator@3.1

您可以通过运行以下命令验证 antora 命令是否在您的路径上可用：

$ antora -v

我们强烈建议您在 playbook 项目中安装 Antora。这种策略使得更容易管理 Antora 的版本。它还确保 Antora 的版本与制作 playbook 的版本匹配。

现在您已经准备好创建您的第一个 playbook。

有关更详细的信息和其他安装方法，请参阅安装 Antora。

创建 playbook

要生成文档站点，Antora 需要一个 playbook。使用您喜欢的文本编辑器或集成开发环境，创建一个新文件并填充配置信息，如下所示。将此文件保存为 antora-playbook.yml，放在您在上一步中创建的 docs-site 目录中。此 playbook 文件将使用Antora 演示存储库创建一个站点。

antora-playbook.yml 
site:
  title: Antora Docs
  start_page: component-b::index.adoc (1)
content:
  sources: (2)
  - url: https://gitlab.com/antora/demo/demo-component-a.git
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui: (3)
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
1 用作站点主页的组件版本页面。
2 sources 类别包含 Antora 在聚合站点内容时使用的 git 存储库位置、分支名称模式和其他存储库属性列表。
3 ui 类别包含指定 UI bundle 位置以及如何处理它的键。
有关 playbook 文件的更详细信息，请参阅Antora playbook。

运行 Antora

要生成站点，请将 antora 命令指向您的 playbook 文件。在终端中，确保您在 docs-site 目录中，然后键入：

$ npx antora --fetch antora-playbook.yml

Antora 将克隆内容和 UI 存储库，并将生成您的文档站点到默认输出目录。

默认情况下，Antora 在克隆存储库后不会同步存储库。相反，它尝试脱机工作，使用先前克隆的缓存中的存储库。这种默认设置在开始时可能会造成一些混乱。因此，我们建议在命令中包含--fetch 选项，直到您更熟悉 Antora。您还可以在 playbook 中设置fetch 键以永久启用此设置。

转到 docs-site/build/site 目录，并在浏览器中打开 index.html 文件以查看结果。恭喜！您已成功使用 Antora 构建了第一个站点。

有关运行 Antora 和故障排除帮助的更详细信息，请参阅运行 Antora 以生成您的站点。

了解更多