将 Antora 用于您的开源文档

您是否正在寻找一种简单的方法来编写和发布技术文档？ 我来介绍一下 安托拉 — 一个开源文档站点生成器。 对于小型项目来说足够简单，但也足够复杂以涵盖大型文档站点，例如 Fedora 文档.

将源存储在 git 中，使用简单但功能强大的标记语言 AsciiDoc 编写，并以静态 HTML 作为输出，Antora 使编写、协作和发布您的文档变得轻而易举。

基本概念

在我们建立一个简单的网站之前，让我们看一下 Antora 用来让世界变得更快乐的一些核心概念。 或者，至少，建立一个文档网站。

组织内容

用于构建文档站点的所有资源都存储在 git仓库. 或多个——可能由不同的人拥有。 为了 example，在撰写本文时， Fedora Docs 将其源存储在 24 个不同的存储库中，这些存储库由不同的团体拥有，它们有自己的贡献规则。

Antora 中的内容被组织成 组件，通常代表项目的不同区域，或者，你正在记录的软件的不同组件——例如后端、UI 等。组件可以独立版本化，每个组件在文档站点上都有单独的空间有自己的菜单。

组件可以选择性地分解成所谓的 模块. 模块在网站上大部分是不可见的，但它们允许您将源组织到逻辑组中，如果您需要这样做，甚至可以将每个模块存储在不同的 git 存储库中。 我们在 Fedora 分开的文件 发行说明、安装指南和系统管理员指南 到三个具有自己规则的不同源存储库中，同时在 UI 中保留一个视图。

这种方法的优点在于，在某种程度上，您的资源的物理结构方式并未反映在网站上。

虚拟目录

在组装站点时，Antora 构建了一个 虚拟目录 在所有页面中，分配一个 唯一身份 根据它的名称和它所属的组件、版本和模块来分配给每一个。 然后页面 ID 用于生成每个页面的 URL，以及内部链接。 因此，在某种程度上，就站点而言，源存储库结构并不重要。

作为一个 example如果我们出于某种原因决定合并所有 24 个存储库 Fedora 文档合二为一，网站上的任何内容都不会改变。 好吧，除了每个页面上的“编辑此页面”链接会突然指向这个存储库。

独立的用户界面

我们已经介绍了内容，但它会是什么样子？

使用 Antora 生成的文档站点使用所谓的 用户界面包 它定义了您网站的外观。 UI 包包含所有图形资产，例如 CSS、图像等，以使您的网站看起来更漂亮。

预计 UI 将独立于文档内容进行开发，而这正是 Antora 所支持的。

把它们放在一起

将源代码分布在多个存储库中可能会引发一个问题：您如何构建站点？ 答案是： 安托拉剧本.

Antora Playbook 是一个指向所有源存储库和 UI 包的文件。 它还定义了其他元数据，例如您的站点名称。

Playbook 是您构建站点所需的唯一本地文件。 作为构建过程的一部分，其他所有内容都会自动获取。

使用 Antora 构建站点

演示时间！ 要构建一个最小的站点，您需要三件事：

  1. 至少一个包含您的 AsciiDoc 源的组件。
  2. 安托拉剧本。
  3. 一个 UI 包

好消息是 Antora 背后的好人提供 example 安托拉资源 我们可以马上试试。

剧本

我们先来看看 剧本：

site:
   title: Antora Demo Site   
# the 404 page and sitemap files only get generated when the url property is set
   url: https://example.org/docs
   start_page: component-b::index.adoc
content:
   sources:
   - url: https://gitlab.com/antora/demo/demo-component-a.git
     branches: master
   - 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/master/raw/build/ui-bundle.zip?job=bundle-stable
     snapshot: true

正如我们所见，Playbook 定义了有关站点的一些信息，列出了内容存储库，并指向 UI 包。

有两个存储库。 这 演示组件-a 有一个分支，并且 演示组件-b 有两个分支，每个分支代表一个不同的版本。

组件

最小的源存储库结构在 演示组件-a 存储库：

antora.yml            <- component metadata
modules/
    ROOT/             <- the default module
        nav.adoc      <- menu definition
        pages/        <- a directory with all the .adoc sources
            source1.adoc
            source2.adoc
            ...

以下

antora.yml 包含该组件的元数据，例如组件的名称和版本、起始页，它还指向一个菜单定义文件。

name: component-a
title: Component A
version: 1.5.6
start_page: ROOT:inline-text-formatting.adoc
nav:
 - modules/ROOT/nav.adoc

菜单定义文件是一个简单的列表，定义了菜单的结构和内容。 它使用 页面编号 识别每一页。

* xref:inline-text-formatting.adoc[Basic Inline Text Formatting]
* xref:special-characters.adoc[Special Characters & Symbols]
* xref:admonition.adoc[Admonition]
* xref:sidebar.adoc[Sidebar]
* xref:ui-macros.adoc[UI Macros]
* Lists
** xref:lists/ordered-list.adoc[Ordered List]
** xref:lists/unordered-list.adoc[Unordered List

最后，下面是实际内容 模块/ROOT/页面/ — 您可以查看示例的存储库，或者 AsciiDoc 语法参考

用户界面包

对于 UI，我们将使用 example 项目提供的 UI。

深入了解 Antora UI 的细节超出了本文的范围，但如果您有兴趣，请参阅 Antora 用户界面文档 了解更多信息。

建设网站

注意：我们将使用 Podman 在容器中运行 Antora。 您可以在 Fedora 杂志。

要构建站点，我们只需要在 Playbook 文件上调用 Antora。

目前获取antora最简单的方法是使用项目提供的容器镜像。 你可以通过运行得到它：

$ podman pull antora/antora

让我们获取剧本存储库：

$ git clone https://gitlab.com/antora/demo/demo-site.git
$ cd demo-site

并使用以下命令运行 Antora：

$ podman run --rm -it -v $(pwd):/antora:z antora/antora site.yml

该网站将在

公共目录。 您可以直接在 Web 浏览器中打开它，也可以使用以下命令启动本地 Web 服务器：

$ cd public
$ python3 -m http.server 8080

您的网站将在 https://localhost:8080.

Related Posts