Antora如何帮助您和您的团队

自动化组装您的安全、灵活的静态站点，随着变化的发生而进行，而不是与CMS巨头搏斗。

对任何更改做出自动重建和部署，响应时间仅为几秒钟。永远不必担心在部署的CMS应用程序中修补安全漏洞，因为您没有一个。所有页面都是静态的—采用JAMstack风格。需要将站点迁移到不同的域？只需重新构建站点并在新主机上重新启动。Antora生成的站点在词义上是静态的。该站点可以在任何Web服务器上运行，在任何域或子域中，在子文件夹中甚至从本地文件系统中运行。

调整您的站点以与其他网络属性无缝匹配。

没有站点是孤立的。站点必须与其他站点友好相处，以保持一致的品牌和用户体验。由Antora生成的静态站点非常适合这个角色。通过页面模板和自动化流程的一点帮助，您可以将您的文档页面融入现有站点，给人一种所有内容都是单一统一站点的印象。

使用基于git的CI工作流来管理文档更改、贡献和倡议。

走向开发所在地。无论是GitHub、GitLab、Bitbucket还是其他代码托管服务，您都可以利用这些平台来开发Docs as Code。基于git的CI工作流不仅为您提供免费的协作和审阅工具，还鼓励跨团队进行协作。结果，文档成为软件开发过程的一部分。这意味着更多的人愿意支持改进文档的努力。

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

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

描述您想要制作的内容，Antora会为您完成。

Antora首先是为作家而建立的。作家想要写作，而不是纠缠于重新配置软件。这就是Antora的playbook的作用。playbook是描述您想要生成的站点的简洁方式。这个描述归结为a）从哪里获取内容，b）将UI应用于页面，c）在哪里发布。这就是Antora需要知道的一切来完成其工作。只有当您寻求额外定制时，您才需要深入了解。

首选离线。

使用Antora生成的站点可以完全离线查看。站点中的所有引用都是自包含的（即相对的），因此您无需运行Web服务器即可查看它。只需在浏览器中打开生成的HTML文件之一，然后您可以从UI导航到所有页面。即使默认情况下，重定向也可以离线工作。如果有Web服务器可用，您可以传递附加配置以告诉Antora利用其功能。

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

大多数站点生成器仅限于单个存储库的单个分支。另一方面，Antora知道如何使用git。它会获取站点所需的所有内容，使用其内置的git客户端。然后，它通过将文件分成组件的版本来对文件进行排序。这使您可以以最适合您的组织方式存储文档，无论是将内容与代码保持一致还是使用单独的存储库。Antora可以收集所有这些不同的项目和存储库，并创建一个集成的站点。

挑选和选择内容以手工制作您的站点。

您并不总是希望在站点中包含所有内容。有时，您只想构建一个包含减少产品或版本选择的“微型站点”。或者您可能只需要预览您当前正在工作的产品的文档。通过调整您从中提取内容的来源，playbook可以让您从相同的内容源中生成站点的多个变体。

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

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

探索不同的产品版本或在不同版本之间导航到页面。

有多个版本的文档可用时，用户需要一种方式导航到这些版本。Antora为读者提供了一个文档组件和版本的目录，呈现为菜单。读者可以浏览菜单，直接跳转到他们需要的文档版本。此外，每个页面都可以自我标识为版本序列的一部分，使用户可以快速访问页面上的旧版本或新版本的内容。

使用专为技术文档而设计的直观语法进行文档编写，该语法既轻量又全面。

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

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

每次输入以前输入过的内容时，您都在失去效率，并引入内容分歧的风险。AsciiDoc提供了几种工具，可以避免重复。您可以使用属性避免多次输入URL、产品名称或定义。您可以使用包含来提取整个段落、部分和其他可重用内容到常见文件中。您还可以引入语法扩展来减少常见重复模式，例如对问题跟踪器的引用，或新类型的内容，例如方程式和图表，以简化。

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

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

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

您可以使用源系统中目标的位置来创建页面和其他资源之间的引用，而不是依赖于生成的文件名或URL。这样做使得理解引用变得容易，因为您只需要考虑目标文件的位置，而不需要考虑它是如何被处理的。换句话说，您保持在源坐标系统中。您还可以获得当前源文件上下文的好处，因此您只需要指定与当前上下文不同的目标特征。

源到源引用提供了必要的信息，以将站点与文件系统和发布环境解耦。

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

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

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

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

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

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

Antora中的一个关键主题是内容和展示的分离。这在用户界面中尤为突出。Antora与作为单独项目存储和管理的站点用户界面进行交互。它将一个UI模型传递给UI提供的Handlebars模板。然后模板决定从模型中显示什么内容，使UI完全控制页面布局。模板还决定包含哪些CSS和JavaScript。

独立于内容对用户界面进行迭代。

由于用户界面和内容是分开维护的，它们可以遵循不同的发布周期。而且不会互相干扰。在用户界面上的工作不会影响内容上的工作。当Antora运行时，它会将最新的内容和最新的用户界面合并在一起。这意味着可以轻松地将一个用户界面和主题与另一个进行交换，这对重新设计、A/B测试或活动可能很有用。您可以最大程度地自定义用户界面及其主题以满足您的需求。

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

变化是必然的。您只需要准备好应对。文档站点中最常见的更改之一是页面的URL，随着页面被重命名或重新组织，URL会发生变化。Antora提供了一种通过声明页面别名来保留旧页面的URL的方法。与Antora中的其他功能一样，这些信息存储在内容中，这种情况下存储在目标AsciiDoc文档的头部。

重定向使用别名描述，这些别名只是入站xref，不与URL耦合。

正如您可能期望的那样，页面别名是一个源引用，它允许Antora负责从正确的URL创建重定向。由于不是所有的托管环境都相同，执行重定向的功能也不同。Antora会为托管环境提供的重定向功能生成适当的配置，如果不支持其他机制，则退而求其次使用传统的静态跳转页面。

无论是本地还是远程，都可以发布。

站点是用来发布的。Antora有助于实现这一点。无论目的地是本地还是远程，Antora都可以使用内置或自定义提供程序将内容流式传输到那里。而且，无论站点发布在哪里，站点都不与主机环境耦合。Antora支持您想要的任意数量的输出流，这可以是本地目录、本地存档、远程SSH服务器上的目录，或者像S3这样的Web服务端点，或者是多个目的地的组合。您可以确保Antora将文件发送到需要发布的位置。所有这些都在一个构建中完成。

无需单独的步骤、工具或脚本。

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

从默认设置开始。

Antora提供了一个默认的站点生成器和用户界面，让您可以快速启动。您可以使用antora CLI命令与站点生成器进行交互，您可以自行安装或使用Docker容器调用该命令。只需将命令指向您的playbook，Antora就会为您生成一个多组件、多版本的文档站点。一旦您有机会设置或迁移您的文档以便与Antora一起使用，您就可以从默认设置中毕业，并开始调整Antora以满足高级需求。

为自己定制Antora。

Antora具有开放式架构。这意味着您可以教会Antora新的技巧。也许您需要将额外的内容整合到Antora的目录中。或者您可能希望在某个环节执行自定义处理。您甚至可以引入自己的行为来重新配置Antora以满足您的需求。Antora的设计使您可以在提供的站点生成器不适合您时将其用作基础。