Antora

Antora简介Antora 是一个基于 AsciiDoc 的模块化文档站点生成器由开源贡献者社区维护特别适用于需要管理多版本、多组件文档的大型技术文档项目。它将文档视为代码采用 Git 原生工作流支持从多个仓库聚合内容并统一呈现。核心特点特性说明AsciiDoc 原生支持使用 AsciiDoc 标记语言支持复杂结构化写作模块化架构将文档拆分为独立组件Components可跨项目复用多版本管理原生支持 Git 分支/标签作为文档版本自动构建版本切换多仓库聚合从多个 Git 仓库拉取内容统一生成站点Git 原生工作流完全基于 Git 分支策略管理文档生命周期Playbook 驱动通过 YAML 配置文件定义内容源、站点配置和输出UI 组件化独立的 UI 包UI Bundle系统主题与内容完全分离典型应用场景企业产品文档需要维护多个产品线的多版本文档微服务架构文档各服务文档分散在不同仓库需统一门户开源基金会项目如 Couchbase、Fedora、OpenShift 官方文档复杂版本矩阵软件有多个长期支持版本LTS并行维护核心概念组件Component文档的基本组织单元通常对应一个产品或模块docs/ ├── antora.yml # 组件描述文件名称、版本、导航 ├── modules/ │ ├── ROOT/ # 根模块必备 │ │ ├── pages/ # 页面文件.adoc │ │ ├── images/ # 图片资源 │ │ ├── attachments/# 附件资源 │ │ └── nav.adoc # 导航定义 │ └── admin/ # 可选子模块 │ └── pages/ └── ...版本Version通过 Git 分支或标签定义v2.3.x分支 → 生成 2.3 版本文档v2.2.x分支 → 生成 2.2 版本文档所有版本在站点中并列展示用户可自由切换Playbook站点构建的核心配置文件antora-playbook.ymlsite:title:我的文档站点url:https://docs.example.comstart_page:component-a::index.adoccontent:sources:# 从本地路径加载-url:./component-abranches:[main,v2.3.x,v2.2.x]start_path:docs# 从远程仓库加载-url:https://github.com/org/component-b.gitbranches:[main,v2.*]tags:[v2.3.0,v2.2.0]start_path:docsui:bundle:url:https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?jobbundle-stablesnapshot:trueruntime:fetch:true# 每次构建拉取最新内容asciidoc:attributes:page-pagination:trueid-prefix:id-separator:-快速开始1. 安装# 需要 Node.js 14npminstall-gantora/cli antora/site-generator-default# 验证安装antora--version2. 创建组件结构mkdir-pmy-component/docs/modules/ROOT/pagescdmy-component创建组件描述文件docs/antora.ymlname:my-component# 组件 IDURL 中使用title:我的组件# 显示名称version:2.3# 版本号也可使用 git 分支名prerelease:false# 是否为预发布版本nav:-modules/ROOT/nav.adoc# 导航文件路径3. 编写内容创建首页docs/modules/ROOT/pages/index.adoc 欢迎使用 My Component 这是首页内容使用 AsciiDoc 语法编写。 特性概览 * 模块化架构设计 * 原生多版本支持 * 企业级内容复用 [NOTE] 这是一个提示框AsciiDoc 的 admonition 语法。 代码示例 [source,python] ---- def hello_antora(): print(Hello from Antora!) ----创建导航文件docs/modules/ROOT/nav.adoc* xref:index.adoc[首页] * 用户指南 ** xref:installation.adoc[安装] ** xref:configuration.adoc[配置] * 参考手册 ** xref:api-reference.adoc[API 文档] ** xref:cli-commands.adoc[CLI 命令]4. 创建 Playbook在项目根目录创建site.ymlsite:title:Antora 演示站点start_page:my-component::index.adoccontent:sources:-url:./my-componentbranches:HEADstart_path:docsui:bundle:url:https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?jobbundle-stablesnapshot:trueoutput:dir:./build/site5. 构建站点# 执行构建antora site.yml# 启动本地预览npx http-server build/site-p8080# 开发模式监听变化antora site.yml--fetch高级特性页面别名与重定向在antora.yml中定义 URL 重定向asciidoc:attributes:page-aliases:old-page-name.adoc或在页面头部定义 新页面标题 :page-aliases: old-page.adoc, legacy-page.html 页面内容...内容复用Partials创建可复用的内容片段docs/modules/ROOT/partials/common-steps.adoc. 下载安装包 . 解压到目标目录 . 运行安装脚本在页面中引用include::partial$common-steps.adoc[]跨组件引用// 引用同一版本的其他组件 xref:other-component::index.adoc[其他组件首页] // 引用特定版本 xref:2.2other-component::api.adoc[2.2 版本 API] // 引用最新版本 xref:other-component::api.adoc[最新版本 API]多语言支持通过组件或版本区分语言# antora.yml for Englishname:my-docstitle:Documentationversion:2.3asciidoc:attributes:lang:en# antora.yml for Chinesename:my-docstitle:文档中心version:2.3asciidoc:attributes:lang:zh部署方案GitLab CI/CD原生支持最佳# .gitlab-ci.ymlstages:-build-deploybuild:stage:buildimage:node:18-alpinescript:-npm install-g antora/cli antora/site-generator-default-antora antora-playbook.ymlartifacts:paths:-build/site/expire_in:1 weekpages:stage:deploydependencies:-buildscript:-mv build/site publicartifacts:paths:-publiconly:-mainGitHub Actions# .github/workflows/docs.ymlname:Build Antora Siteon:push:branches:[main]jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4with:fetch-depth:0# 需要完整历史以获取所有分支/标签-uses:actions/setup-nodev4with:node-version:18-name:Install Antorarun:npm install-g antora/cli antora/site-generator-default-name:Build siterun:antora antora-playbook.yml-name:Deploy to GitHub Pagesuses:peaceiris/actions-gh-pagesv3with:github_token:${{secrets.GITHUB_TOKEN}}publish_dir:./build/siteNetlify/Vercel# build 命令npminstall-gantora/cli antora/site-generator-defaultantora antora-playbook.yml# publish 目录build/site常用扩展与工具工具/扩展功能antora/lunr-extension添加客户端搜索功能antora/pdf-extension生成 PDF 输出asciidoctor-diagram支持 PlantUML、Mermaid 等图表asciidoctor-kroki集成 Kroki 图表服务antora-collector-extension从非 Antora 结构收集内容antora-aggregate-collector高级内容聚合学习资源官方文档https://docs.antora.orgAsciiDoc 语法https://docs.asciidoctor.org/asciidoc/latest/UI 开发指南https://docs.antora.org/antora-ui-default/Antora 的核心价值在于将文档管理提升到与代码管理同等的成熟度——通过 Git 分支管理版本、通过模块化实现复用、通过 Playbook 实现多源聚合特别适合需要长期维护复杂文档矩阵的企业环境。