Antora 如何帮助您和您的团队

在发生变化时自动组装安全、灵活的静态站点，而不是与 CMS 巨头角力。

在响应任何更改的几秒钟内自动重新构建和部署您的站点。由于没有安全漏洞，因此不必担心修补已部署 CMS 应用程序中的安全漏洞。所有页面都是静态的 JAMstack 样式。需要将站点迁移到不同的域名? 仅需要重建网站，在新域名上重新启动。

调整您的网站，使其与您的其它网站属性无缝匹配。

没有一个地方是孤岛。网站必须与其他网站友好相处，以保持一致的品牌和用户体验。由 Antora 生成的静态站点非常适合这个角色。使用页面模板和自动化过程的一点帮助，您可以将文档页面混合到现有站点中，给人的印象是它是单个统一站点的所有部分。

使用基于 git 的 CI 工作流来管理文档变更、贡献和计划。

哪里有开发，就去哪里。无论是 GitHub 、 GitLab 、 Bitbucket 还是其它代码托管服务，你都可以利用这些平台将文档开发为代码。基于 git 的 CI 工作流不仅为您提供了免费的协作和审查工具，而且还鼓励跨团队进行协作。因此，文档成为软件开发过程的一部分。这意味着更多的人愿意支持改进文档的努力。

通过利用现有的开发基础设施来管理团队和权限。

很有可能，您的软件产品已经有一个定义良好的团队、权限结构和贡献者社区。您可以使用相同的组织或在其基础上构建来管理您的文档团队。这些平台可以作为文档的管理和管理界面，无论是监视活动还是授予执行某些操作的访问权限。

描述一下你想做什么，然后 Antora 从那开始。

Antora 最初是为作家建造的。作者想要的是写作，而不是重新配置软件。这就是 Antora 的剧本发挥作用的地方。剧本是一种简洁的方式来描述你想要制作的网站。这个描述可以归结为a)从哪里获取内容，b)在页面上应用什么UI，以及c)在哪里发布内容。这就是 Antora 完成任务所需要知道的一切。只有在寻找额外的定制时，才需要更深入地研究。

Offline first(先离线) 是一种软件开发原则，其目的是确保应用程序能够在没有可靠的互联网连接时正常工作。这通常涉及设计应用程序的数据模型、缓存、同步机制和网络请求策略。将“先离线”原则应用于应用程序可以提高用户体验，减少应用程序因网络问题而无法使用的风险。

使用 Antora 生成的网站可以完全离线查看。网站中的所有引用都是自包含的(即，相对的)，所以你不需要运行 web 服务器来查看它。只需在浏览器中打开其中一个生成的 HTML 文件，就可以从那里导航到 UI 中的所有页面。即使重定向在默认情况下也离线工作。如果有一个可用的 web 服务器，您可以传递额外的配置来告诉 Antora 利用它的功能。

使用单个构建来聚合跨越存储库边界和分支的文档。

大多数站点生成器都局限于单个存储库的单个分支。另一方面， Antora 知道怎么与 git 沟通。它使用内置的 git 客户端收集网站所需的所有内容。然后，它通过将文件分成组件的不同版本来对它们进行排序。这允许您以最适合您的组织的方式存储文档，无论这意味着将内容与代码一起保存还是使用单独的存储库。Antora 可以收集所有这些不同的项目和存储库，并创建一个集成的站点。

挑选和选择内容来手工制作您的网站。

您不会总是希望在站点中包含所有内容。有时，您只是想构建一个包含较少产品或版本选择的微型站点。或者，您可能只是需要预览当前正在开发的产品的文档。剧本允许您从相同的内容源生成多个站点的变体，只需调整您从哪些来源绘制。

将产品的每个版本构建为一个站点的一部分。

由于软件是版本化的，因此它的文档也需要进行版本化。否则，用户将不知道他们正在阅读的文档涵盖了软件的哪个版本。混乱随之而来。与软件一样，您可以使用分支和标记来管理文档的版本。这些内容甚至可以与软件本身一起存储。Antora 很高兴地收集了所有这些内容，并对其进行了组织，以便用户可以访问每个版本的文档，所有这些都在一个站点下。

浏览不同的产品版本或在不同版本的页面之间导航。

由于有多个版本的文档可用，用户需要一种导航到它们的方法。Antora 提供了一个文档组件和版本的目录，以菜单的形式呈现给读者。读者可以扫描菜单，直接跳转到他们需要的文档版本。此外，每个页面都可以自我识别为版本序列的一部分，允许用户快速访问页面上内容的旧版本或新版本。

使用专为技术文档设计的直观语法的文档，轻量级但全面。

在编写文档时，最不希望遇到的就是标记语法。为了创建最好的内容，您需要能够看到您正在编写的内容，但仍然能够适当地表示不同的内容类型。这正是 AsciiDoc 所提供的。其面向行、左对齐的语法易于浏览，并为应用足够的元数据来构建语义结构留出了空间。AsciiDoc 是文档作者最好的朋友。

使用可重用的属性、包含和语法扩展来保持内容 DRY。

每次你输入一些你以前输入过的东西，你就会失去效率，并带来内容不一致的风险。AsciiDoc 提供了几个工具，使您不必重复。您可以使用属性来避免多次键入 url、产品名称或定义。可以使用 include 将整个段落、节和其他可重用内容提取到公共文件中。您还可以向语法引入扩展，以减少常见的重复模式(例如对问题跟踪器的引用)或新类型的内容(例如公式和图表)速记。

页面只是可以在任何文本编辑器中编辑的 AsciiDoc 文档。

在文档中创建页面与创建 AsciiDoc 文档一样简单。文档可以在文本编辑器中打开和预览，也可以在站点的上下文中查看。Antora 为该页分配了一个隐式ID，以便可以从其他页面引用该页，并且可以使用这些页面的隐式 ID 引用其他页面。章节标题、警告块和突出显示的源代码列表等功能都要有适当的样式。

使用简洁且易于构造的源对源 xref 系统在页面和其他资源之间创建引用。

您不依赖于生成的文件名或 url ，而是使用源系统中目标的位置在页面和其它资源之间创建引用。这使得对引用的推理变得容易，因为您只需要考虑源文件的位置，而不需要考虑如何处理它。换句话说，你停留在源坐标系中。您可以从当前源文件的上下文中获益，因此您只需要指定与当前上下文不同的目标特征。

源到源引用提供了必要的信息，将站点与文件系统和发布环境分离开来。

通过使用资源 ID 表示引用，Antora 可以智能地在未与文件系统或发布环境耦合的已发布输出中创建指向资源的链接。这意味着生成的网站可以在任何地方查看，包括离线。

使用AsciiDoc列表描述文档导航。

使用 Antora 的作者在定义导航时可以感觉很自在。为什么?因为，像页面一样，导航只是另一个 AsciiDoc 文档。但是导航文件不是自由格式的内容，而是包含一个列表层次结构，它被转换成导航菜单侧边栏中看到的导航树。要添加另一个导航树，只需添加一个额外的列表。

使用与主内容相同的xref系统创建导航链接。

那么，如何从导航中创建到页面的链接呢?当然是使用 xref 。由于导航文件只是内容，因此它可以使用与主内容相同的 xref 系统来创建页面之间的链接。可以把导航文件看作一个没有发布的页面。由于文件与内容一起存储，所以 xref 可以是上下文的，这意味着您只需要指定与当前上下文不同的目标特征。

站点的用户界面和主题是与内容分开维护。

Antora 的一个关键主题是内容和表示的分离。这在 UI 中非常明显。Antora 与作为单独项目存储和管理的站点 UI 接口。它将 UI 模型传递给 UI 提供的 Handlebars 模板。然后模板决定从模型中显示什么，让 UI 完全控制页面布局。模板还决定要包含哪些 CSS 和 JavaScript 。

独立于内容迭代 UI 。

由于 UI 和内容分别维护，它们可以遵循不同的发布周期，从而不会相互干扰。在更新 UI 时，不会对内容工作造成影响。当 Antora 运行时，它会将最新的内容和最新的 UI 融合在一起。这意味着可以轻松地用另一个 UI 和主题替换现有的 UI 和主题，这对于重新设计、A/B 测试或推广活动非常有用。您可以自由地定制 UI 及其主题，以满足自己的需求。

通过将信息存储在目标文档中，以透明的方式保留旧页面的 url 。

会发生变化。你只需要准备好面对它。文档站点中最常见的变化之一是页面的 url ，它会随着页面的重命名或重组而变化。Antora 提供了一种通过声明页面别名来保留旧页面 url 的方法。与 Antora 中的其他特性一样，这些信息与内容一起存储，在本例中存储在目标 AsciiDoc 文档的标头中。

重定向使用别名来描述，别名只是入站 xref;没有与 url 耦合。

如您所料，页面别名是一个源引用，它允许 Antora 负责从正确的 URL 创建重定向。由于并非所有托管环境都是相同的，因此执行重定向的工具也不相同。Antora 为托管环境提供的重定向功能生成适当的配置，如果不支持其他机制，则返回到老式的静态反弹页面。

在任何地方发布，无论是本地还是远程。

网站是用来发布的。Antora 能帮上忙。无论目的地是本地还是远程，Antora 都使用内置或自定义提供程序对那里的内容进行流传输。但是，无论在哪里发布站点，站点都不会与主机环境耦合。Antora 支持任意多的输出流，可以是本地目录、本地存档、远程SSH服务器上的目录、web服务端点(如S3)或目的地的组合。你可以确保 Antora 把文件放到需要发布的地方。所有都在一个单独的构建中。

在管道中不需要单独的步骤、工具或脚本。

Antora 的文件发布程序为您节省了一个步骤。大多数站点生成器将输出写入本地目录，然后您必须转身并发布该目录。Antora 将输出直接发送到您指定的目的地。由于站点中的引用与发布环境没有耦合，因此您甚至可以通过将站点发布到本地目录来离线预览站点。

从默认值开始。

Antora 提供了一个自以为是的网站生成器和用户界面，所以你可以快速启动和运行。您可以使用 antora CLI 命令与站点生成器交互，您可以自己安装或使用 Docker 容器调用该命令。只需将命令指向剧本，Antora 就会为您弹出一个多组件、多版本的文档站点。一旦您有机会设置或迁移文档以便与 Antora 一起使用，您就可以放弃默认设置并开始调整 Antora 以适应高级需求。

为你量身定做 Antora 。

Antora 的特点是开放式架构。这是什么意思?这意味着你有能力教 Antora 新把戏。也许您需要将其他内容合并到 Antora 的目录中。或者，您可能希望在某个地方执行自定义处理。您甚至可以引入自己的行为来重新配置 Antora 以满足您的需求。当提供的网站生成器不适合您时，您可以使用 Antora 作为基础。