运行Antora生成您的网站

假设：

您已经安装了 Antora CLI 和一个站点生成器管道。
你有你自己的剧本，或者你正在使用 Demo 剧本。
您的剧本被配置为访问至少一个包含内容源文件的您自己的存储库或 Antora 的 Demo 内容存储库。
您的剧本被配置为使用自定义 UI 包或 Antora 的默认 UI 包。

在这一页，你会学到：

如何运行 Antora 并生成一个站点。

Antora演示剧本和内容存储库

您不需要设置剧本文件、组件版本或 UI 来评估 Antora 。相反，您可以使用 Antora 演示剧本和内容存储库。

该演示由包含剧本文件的剧本存储库和剧本所引用的内容存储库(component-a 和 component-b)组成。它还使用默认 UI 项目生成的 UI 包。

安装完 Antora 后，您可以使用演示材料运行 Antora ，以探索其功能。本页的说明和示例将指导您完成整个过程。

选择一个剧本

为了制作一个文档网站，Antora 需要一个剧本。但首先，您需要创建或选择一个目录，用于存储剧本和保存生成的站点文件(假设您使用默认输出配置)。

对于本页上的示例，我们将使用演示剧本和内容存储库。

打开终端并创建一个名为 demo-site 的新目录。
```
~ $ mkdir demo-site
```
切换( cd )到您刚刚创建的目录。
```
~ $ cd demo-site
```

使用您喜欢的文本编辑器或 IDE ，创建一个名为 antora-playbook.yml 的新剧本文件。并使用以下示例的内容填充它。或者，您可以从演示项目存储库下载剧本文件。

Example 1. antora-playbook.yml

site:
  title: Antora Demo Site
  url: https://my-antora-demo-site.org (1)
  start_page: component-b::index.adoc (2)
content:
  sources:
  - 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:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

1	404 页面和站点地图文件只有在设置了站点 `url` 键后才会生成。只有当站点 `url` 键的值是绝对 `url` 时，才会生成站点地图文件。
2	站点 `start_page` 键接受与 `xref` 中使用的相同的资源 `ID` 语法。

将剧本保存在步骤1中创建的 demo-site 目录中 antora-playbook.yml。

运行 Antora

要使用默认的 Antora 站点生成器生成站点，请将 Antora 命令指向剧本文件。在终端输入：
demo-site $ antora antora-playbook.yml
如果 Antora 是本地安装的，则需要在 Antora 命令前加上 npx ：
demo-site $ npx antora antora-playbook.yml
Antora 将克隆内容存储库。终端显示每个存储库的克隆进度。
Example 2. Repository cloning progress
[clone] https://gitlab.com/antora/demo/demo-component-a.git [################] [clone] https://gitlab.com/antora/demo/demo-component-b.git [################]
克隆操作完成后，Antora 将 AsciiDoc 页面转换为可嵌入 HTML，并将 HTML 封装在 UI 页面模板中，然后将页面组合到站点中，在目标文件夹下生成站点，默认为 build/site 。

当在终端中再次出现命令提示符($)时，Antora 已经完成了生成。如果终端是交互式的（TTY），Antora 还会打印一个消息，指出站点生成已完成。该消息将包括您可以在本地查看站点的 URL 。（您可以通过将 IS_TTY 环境变量设置为 true 或 false 来覆盖 Antora 的 TTY 检测）。

如果在生成过程中出现错误，您将在终端中看到一条错误消息。

error: a message that summarizes what went wrong

如果此消息没有提供足够的信息来解决问题，您可以向 Antora 询问更多的上下文。要告诉 Antora 显示导致错误的调用栈，请再次运行 Antora 命令，这次使用 --stacktrace 选项：

demo-site $ antora --stacktrace antora-playbook.yml

在寻求帮助时分享这个堆栈跟踪。

切换到站点文件夹( cd )并列出( ls )其内容。
demo-site $ cd build/site/
在 build/site 文件夹中，运行：
site $ ls -1
您应该看到下面的文件和目录列表：
_ 404.html component-a component-b index.html sitemap-component-a.xml sitemap-component-b.xml sitemap.xml
NOTE

如果 playbook 中未定义 site.url 属性，则 404 页面和站点地图文件将丢失。主站点地图文件实际上是一个站点地图索引。该文件链接到每个组件的站点地图，在其中可以找到单个页面的 URL。

该列表包括文档站点的入口点 index.html 。
在某些操作系统上，您可以直接从命令行打开站点，只需键入 open ，后跟 HTML 文件的名称。
site $ open index.html
或者，你可以在浏览器中导航到目标文件夹内的 HTML 页面。如果你一直在按照演示材料操作，一旦找到 demo-site 目录，请导航到 build/site/index.html 文件。

私有git存储库

Antora 可以使用基于 HTTPS 的 HTTP 基本身份验证与私有存储库进行身份验证。请参阅私有存储库身份验证了解更多信息。