快速安装和运行 Antora

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

在这一页，你将学习:

如何安装 Node.js 。
如何安装 Antora 。
如何创建你的第一个 Antora 剧本。
如何运行 Antora 生成基于剧本的网站。

安装 Node.js

Antora 需要 Node.js 的长期支持(LTS)版本。要查看是否安装了 Node.js ，以及安装了哪个版本，打开终端并输入：

node -v

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

node --version
v16.20.0

如果您的机器上有一个活动的 Node.js LTS 版本，那么就可以安装 Antora 了。

如果终端没有显示版本号，则需要安装 Node.js 。我们建议使用 nvm 来安装 Node.js ，但您可以自由选择不同的路径。按照这些指南之一学习如何在您的平台上安装 nvm 和 Node.js 。

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

Example 1. Linux and macOS

nvm install --lts
nvm alias default 16

Example 2. Windows

 nvm install 16.20.0
 nvm alias default 16.20.0

安装完 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.3
@antora/site-generator: 3.1.3

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

您可以选择全局安装 Antora ，以便在您的 PATH 上可以使用 Antora 命令。为此，将 -g 选项传递给 npm i 。

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

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

antora -v

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

现在您已经准备好创建第一个剧本了。

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

创建一个 playbook

为了制作一个文档网站，Antora 需要一个剧本。使用您喜欢的文本编辑器或 IDE，创建一个新文件，并用下面列出的配置信息填充它。将此文件在 docs-site 保存为 antora-playbook.yml 。这个剧本文件将使用 Antora 演示存储库创建一个站点。

Example 3. 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` 类别包含 git 存储库位置、分支名称模式和其他存储库属性的列表，Antora 在聚合站点内容时使用这些属性。
3	`ui` 类别包含指定 ui 包的位置以及应该如何处理它。 TIP 有关剧本文件的更多详细信息，请参阅 Antora 剧本。

运行 Antora

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

npx antora --fetch antora-playbook.yml

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

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

导航到 docs-site/build/site 目录，然后在浏览器中打开 index.html 文件以查看结果。恭喜！您已经成功地使用 Antora 建立了第一个网站。

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

了解更多

了解如何为Antora 组织您的内容文件。