Apache Maven Doxia 2.2.0 介绍与选型指南

目标：基于官方站点、Maven Central 与 GitHub Release，讲清 Apache Maven Doxia 2.2.0 的定位、Sink/Parser 内容管线、格式矩阵、适用边界，并给出与 Asciidoctor/Sphinx/MkDocs/Hugo 的量化选型对比。本文为认知篇，全部论断联网溯源（查询日期 2026-10-19），不做本地安装实测。

一、信息基准

• 查询日期：2026-10-19（本文所有版本号、星标数、日期均在该日联网核验）。
• 版本依据：GitHub 仓库 apache/maven-doxia 最新 Release 为 doxia-2.2.0（Release 页时间 2026-10-18，Releases Atom 流实查）；Maven Central 上 org.apache.maven.doxia:doxia-core:2.2.0 的 jar 直链实查可访问（HTTP 200），doxia 聚合元数据已列入 2.2.0（metadata lastUpdated 2026-10-18）。2.2.0 即官方当前最新稳定版，发布刚一天，文档站点尚未同步。
  • ⚠️ 注意：官方站点 https://maven.apache.org/doxia/ （页面标注 Last Published: 2026-09-27）仍写 "The current version of Doxia base framework is 2.1.0"，属站点滞后；Doxia Site Tools 组件线当前为 2.1.0（Maven Central doxia-site-renderer latestVersion 2.1.0 实查）。若需要"久经时间验证"的基线，2.1.0 是上一个稳定版（2.0.0 → 2.1.0 → 2.2.0 的演进序列见 Maven Central metadata）。
• 维护方：Apache Maven 项目（Maven PMC），Doxia 自 2006 年初成为 Maven 的子项目。
• 许可：Apache License 2.0（Apache Maven 项目统一许可）。
• 发行形态：Maven Central 构件（org.apache.maven.doxia:doxia-core、doxia-module-*、doxia-sink-api 等）；与 Maven Site Tools（doxia-sitetools）配合完成站点渲染；另有独立工具 Doxia Converter。
• 代码仓库：https://github.com/apache/maven-doxia （GitHub 星标 33、贡献者 45，shields.io 实查，查询日期 2026-10-19）。
• 官方来源清单：
  • 官方站点：https://maven.apache.org/doxia/
  • 格式参考（各标记语言对照）：https://maven.apache.org/doxia/references/index.html
  • 模块清单：https://maven.apache.org/doxia/modules/index.html
  • Site Tools：https://maven.apache.org/doxia/doxia-sitetools/
  • Doxia Converter：https://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html
  • GitHub Releases：https://github.com/apache/maven-doxia/releases

二、软件概述

2.1 项目定位与版本

Apache Maven Doxia 2.2.0（2026-10-18 发布）是一个内容生成框架（content generation framework），官方定位是"为用户提供生成静态与动态内容的强大技术"：既能在 Web 发布场景生成静态站点，也能嵌入博客、Wiki、CMS 等动态内容系统。它最广为人知的角色是 Maven 整个文档体系的底层引擎——Maven 的 mvn site 站点、项目报告、FAQ 页全部由 Doxia 驱动。

Doxia 的核心价值主张是"一种中间模型，多种输入格式，多种输出格式"：开发者用任意一种受支持的轻量标记语言（APT、Markdown、FML、XDoc、XHTML 等）写作，Doxia 负责解析成统一文档模型，再渲染为 HTML/PDF/RTF 等任意目标格式。

2.2 历史沿革

官方站点" Brief History"记载：Doxia 前身是 Xmlmind 开发的（现已终止的）Aptconvert 项目，最初托管于 Codehaus，2006 年初成为 Maven 子项目。2.x 版本线自 2024 年底的 2.0.0 起步入现代化阶段，当前演进到 2.2.0。

三、核心架构

3.1 Sink/Parser 双向内容管线

Doxia 的架构核心是一对对称接口（来源：官方站点与 2.x 源码结构）：

• Parser（解析器）：把一种标记语言解析为 Doxia 中间文档模型（如 doxia-core 中的 Sink 事件流/文档对象）。每种输入格式对应一个 doxia-module-* 模块（如 doxia-module-markdown、doxia-module-apt）。
• Sink（输出槽）：把中间模型写出为目标格式——HTML Sink、XDoc Sink、PDF（via fo）Sink、RTF Sink 等。新增一种输出格式即实现一个 Sink，无需触碰解析侧。

这条管线的设计意义在于格式自由组合：m 种格式输入 × n 种格式输出只需 m+n 个组件，而不是 m×n 个转换器。

💡 技术拓展：文档引擎的"中间模型"路线并非唯一——

路线	代表	特点
中间模型双向管线	Doxia（Sink/Parser）	一次解析多路输出，与构建工具深度集成
单一源格式直译	Asciidoctor（AsciiDoc→HTML/PDF）	源格式表现力强，输出收敛
约定优于配置的站点生成器	MkDocs、Hugo	面向整站，主题/导航/搜索开箱即用

Doxia 因绑定 Maven 生态而选择前者：报告（changes、FAQ、依赖报告）都能作为"文档流"进站点。

3.2 Site Tools 与 Tools 扩展

• doxia-sitetools：站点渲染扩展，包含 doxia-site-renderer（站点页渲染）、doxia-decoration-model（站点皮肤/导航装饰模型）等，mvn site 的外观与布局由它实现（当前版本线 2.1.0）。
• doxia-tools：独立工具集，其中 Doxia Converter 可在两种标记格式之间直接互转（如 APT→Markdown）。
• 宏（Macro）：APT 等格式支持宏扩展（如 snippet 宏嵌入代码片段）。

四、关键特性

依据官方站点 Main Features 归纳（查询日期 2026-10-19）：

• 多格式支持：APT（Almost Plain Text）、Markdown、FML（FAQ Markup Language）、XDoc（Apache 圈常用）、XHTML；2.2.0 起 FML 模块被标记为弃用（GitHub Release 2.2.0 变更记录：Deprecate doxia-module-fml）。
• 语法易学：轻量标记语言面向"既读源码又读渲染结果"的人群设计。
• 宏支持：snippet 等宏减少文档与代码的重复。
• 无需基础设施：不依赖 Wiki 等企业基础设施即可承载文档。
• 可扩展框架：新 Parser/Sink/模块按接口扩展。
• Site Tools 扩展：站点与文档渲染的完整配套。
• 2.2.0 主要变更（GitHub Release 2.2.0，2026-10-18）：弃用 doxia-module-fml；停止为外部链接附加 externalLink class（破坏性变更）等。

五、快速上手

以下路径转述自官方文档（来源：https://maven.apache.org/doxia/ 与 Maven Site Plugin 文档，查询日期 2026-10-19）。对绝大多数用户，Doxia 的使用入口是 Maven Site Plugin，而非直接调用 API：

路径一：作为 Maven 项目的文档引擎（推荐）

# 1. 在 pom.xml 中配置 maven-site-plugin（Maven 项目自带站点机制）
# 2. 按约定放置文档源：
#    src/site/apt/index.apt        — APT 格式
#    src/site/markdown/usage.md    — Markdown 格式
#    src/site/site.xml             — 站点导航与皮肤（decoration model）
# 3. 生成站点：
mvn site
# 输出位于 target/site/，浏览器打开 index.html 查看

路径二：格式互转（独立工具）

使用官方 Doxia Converter（maven.apache.org/doxia/doxia-tools/doxia-converter/）可在 APT/XDoc/Markdown 等格式间转换存量文档，适合从旧格式迁移。

路径三：API 嵌入（Java 库形态）

<dependency>
  <groupId>org.apache.maven.doxia</groupId>
  <artifactId>doxia-core</artifactId>
  <version>2.2.0</version>
</dependency>

自定义渲染时实现/调用 Sink 接口（doxia-sink-api），把文档模型写到任意目标格式；自定义解析时实现 Parser 接口接入新标记语言。

六、适用场景与限制

适用场景：

• Maven 项目的站点与项目报告文档（mvn site 体系的默认与原生选择）；
• 需要"同一批文档源多种输出"或需要在构建期把文档生成嵌入 Java 构建的工程；
• 存量 APT/XDoc 格式文档的维护与互转。

限制与注意：

• 生态位绑定 Maven：脱离 Maven 单独做通用文档站时，Doxia 的站点能力（主题、搜索、多语言）远不如 MkDocs/Sphinx/Hugo 成熟；
• 站点组件版本线不同步：Doxia 核心已 2.2.0，Site Tools 仍在 2.1.0 线，升级时需分别核对兼容矩阵；
• FML 已弃用：FAQ 类内容建议改用 Markdown/其他格式承载（2.2.0 弃用 doxia-module-fml）；
• 社区规模有限：GitHub 仓库 33 星、45 贡献者，属"维护型"组件，新特性取决于 Maven 生态本身的需求。

七、同类选型对比

数据来源：shields.io 聚合的 GitHub 数据与各项目 Release 页，查询日期 2026-10-19。

选型解读：

• 项目已是 Maven 构建、文档需求是"项目站点 + 报告"，选 Doxia——它是 mvn site 的原生引擎，无第二选择；
• 追求源格式表现力（表格、条件块、include）与 PDF 输出，选 Asciidoctor；
• 技术文档要版本化 API 文档、多语言、搜索，选 Sphinx；
• Markdown 为王、想要漂亮文档站且配置最省心，选 MkDocs；
• 面向"文档+博客"整站、追求极致构建速度，选 Hugo。
• Doxia 的星标/贡献者数量与其"引擎被 Maven 隐性使用"的定位相符——它不是靠社区活跃度取胜，而是靠生态绑定。

八、参考链接

• 官方站点：https://maven.apache.org/doxia/
• 标记语言参考：https://maven.apache.org/doxia/references/index.html
• 模块清单：https://maven.apache.org/doxia/modules/index.html
• Doxia Site Tools：https://maven.apache.org/doxia/doxia-sitetools/
• Doxia Converter：https://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html
• 代码仓库：https://github.com/apache/maven-doxia
• GitHub Releases（2.2.0 变更记录）：https://github.com/apache/maven-doxia/releases
• Maven Central（doxia-core）：https://repo1.maven.org/maven2/org/apache/maven/doxia/doxia-core/