Apache Maven Doxia 2.1.0 集成使用实战详解
在 Ubuntu 22.04 上从零跑通 maven-site-plugin 3.21.0 站点生成与 doxia-converter 格式互转的完整实战记录，含三个真实踩坑与修复。
Apache Maven Doxia 2.1.0 集成使用实战详解
目标：在 Ubuntu 22.04 上用 maven-site-plugin 3.21.0 生成多格式源页面站点，并源码构建 doxia-converter 1.3 完成 APT 与 Markdown 互转，已在 Ubuntu 22.04 实测通过。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| 架构 | x86_64 |
| JDK | OpenJDK 17.0.20.1 |
| Maven | 3.6.3（系统源安装） |
| 站点插件 | maven-site-plugin 3.21.0 |
| 皮肤 | maven-fluido-skin 2.1.0 |
| 转换器 | doxia-converter 1.3（源码构建） |
| 实测目录 | /opt/doxia/demo（站点项目）、/opt/doxia/doxia-converter-1.3（转换器源码） |
| 依赖仓库 | https://maven.aliyun.com/repository/public |
环境准备只做了两件事：用系统包管理器安装 openjdk-17-jdk 与 maven，以及为 Maven 配置国内镜像。版本确认回显如下：
$ java -version
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
$ mvn -version
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
镜像配置写入 /root/.m2/settings.xml，只镜像 central：
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
<mirrors>
<mirror>
<id>aliyun</id>
<mirrorOf>central</mirrorOf>
<name>Aliyun Central</name>
<url>https://maven.aliyun.com/repository/public</url>
</mirror>
</mirrors>
</settings>
settings.xml 逐项说明：id 是镜像本地标识；mirrorOf 为 central 表示只接管中央仓库而不影响其他仓库；url 为阿里云公共仓库聚合地址。实测全部插件与皮肤构件均能从该镜像拉取，总下载时间约 2 分钟（首次构建）。
二、依赖引入与项目准备
2.1 项目 POM
站点项目不需要引入任何 doxia 依赖——site 插件自带解析管线。/opt/doxia/demo/pom.xml 全文如下：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>doxia-site-demo</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<name>Doxia Site Demo</name>
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.21.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
</plugin>
</plugins>
</build>
</project>
要点解读：packaging 用 jar 即可，site 生成不依赖特殊打包类型；maven-site-plugin 显式钉在 3.21.0，确保绑定 Doxia 2.x 管线；编译插件钉 3.13.0 以配合 JDK 17；sourceEncoding 声明 UTF-8，保证中文 APT/Markdown 源文件按 UTF-8 解析。
2.2 目录结构
按 Maven 站点约定建目录：
/opt/doxia/demo/
├── pom.xml
└── src/site/
├── site.xml # 站点描述符（装饰模型）
├── apt/ # APT 源页面
│ ├── index.apt
│ └── apt-usage.apt
└── markdown/ # Markdown 源页面
└── markdown-usage.md
目录与格式的映射规则：src/site/apt 下 .apt 文件走 APT 解析器，src/site/markdown 下 .md 文件走 Markdown 解析器，Xdoc 放 src/site/xdoc，FML 放 src/site/fml。输出统一到 target/site，文件名与源文件主名对应（index.apt 生成 index.html）。
三、站点生成实战
3.1 站点描述符 site.xml
Doxia 2.x 时代的第一个坑就在这里。实测可用的 site.xml 全文：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/DECORATION/1.8.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 http://maven.apache.org/xsd/decoration-1.8.0.xsd"
name="Doxia Site Demo">
<bannerLeft>
<name>Doxia Site Demo</name>
<href>https://maven.apache.org/doxia/</href>
</bannerLeft>
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId>
<version>2.1.0</version>
</skin>
<body>
<menu name="项目文档">
<item name="首页" href="index.html"/>
<item name="APT 用法" href="apt-usage.html"/>
<item name="Markdown 用法" href="markdown-usage.html"/>
</menu>
</body>
</project>
逐项说明：DECORATION 1.8.0 命名空间是当前插件可接受的装饰模型版本（构建时有迁移告警，见 3.5）；bannerLeft 定义左上角横幅文字与链接；skin 节点在 3.21.0 下是必需项，实测选用 maven-fluido-skin 2.1.0 与 Doxia Sitetools 2.1.0 同代匹配；body/menu 定义左侧导航，item 的 href 指向生成后的 HTML 文件名。
💡 技术拓展：皮肤选择有两个候选——maven-default-skin（停更于 1.3，只兼容旧渲染模板）与 maven-fluido-skin（现行版本 2.1.0，兼容新模板）。实测 3.21.0 插件必须用后者，本文采用 maven-fluido-skin 2.1.0。
3.2 三个真实踩坑与修复
坑一：skin cannot be null。 按 1.x 时代习惯不写 skin 节点直接构建，实测失败：
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.21.0:site
(default-site) on project doxia-site-demo: Execution default-site of goal
org.apache.maven.plugins:maven-site-plugin:3.21.0:site failed: skin cannot be null
-> [Help 1]
修复：在 site.xml 增加 skin 节点（如 3.1 所示）。
坑二：Skin does not contain template at META-INF/maven/site.vm。 顺手填了 maven-default-skin 1.3（老版皮肤），实测再次失败：
[INFO] Downloaded from aliyun: https://maven.aliyun.com/repository/public/org/apache/maven/skins/maven-default-skin/1.3/maven-default-skin-1.3.jar
[INFO] Rendering content with org.apache.maven.skins:maven-default-skin:jar:1.3 skin
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.21.0:site
(default-site) on project doxia-site-demo: Failed to create context for skin:
Skin does not contain template at META-INF/maven/site.vm -> [Help 1]
原因是 1.3 皮肤只带旧版 Velocity 模板路径，不含 2.x 管线要求的 META-INF/maven/site.vm。实测查询阿里云仓库元数据：maven-default-skin 最新就是 1.3（无 2.x 版本），maven-fluido-skin 有 2.1.0。修复：换用 maven-fluido-skin 2.1.0。
坑三：APT 章节层级解析失败。 把 APT 页面的章节标题写成一级 * 标题、二级 ** 标题（Markdown 直觉），实测报错：
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.21.0:site
(default-site) on project doxia-site-demo: Failed to render site: Error parsing
'/opt/doxia/demo/src/site/apt/index.apt', line 11: AptParseException: expected
SECTION1, found SECTION2 -> [Help 1]
对照 Doxia 源码自带的官方测试文件 test.apt 才确认：APT 语法里一级章节是列 0 的纯文本行，* 前缀已经是二级章节，** 是三级。修复：改为一级章节直接写文本行、二级章节用单星号。这条与 Markdown 的心智模型完全相反，是 APT 实操最容易踩的坑。
3.3 APT 源页面实测
修正后的 /opt/doxia/demo/src/site/apt/index.apt 全文：
------
Doxia 站点首页
------
zhou
------
2026-10-15
------
这是一个通过 {{{https://maven.apache.org/doxia/}Apache Doxia}} 渲染的 APT 页面。
小节标题
APT 是 "Almost Plain Text" 的缩写，是 Doxia 的原生格式之一。
* 二级小节
下面是一个列表：
* 第一项
* 第二项
下面是一段代码：
+---+
public class Hello {
public static void main(String[] args) {
System.out.println("Hello Doxia");
}
}
+---+
语法要点逐条说明：标题块由四个缩进的六连字符分隔行夹住标题、作者、日期三行（分隔行必须缩进，实测列 0 的分隔行不会被识别为标题块）；正文段落缩进两格；列 0 纯文本行为一级章节；* 开头为二级章节；无序列表项以缩进的 * 起始；+---+ 围栏内为原样代码块；{{{URL}文字}} 为超链接。表格语法实测另见格式与配置篇。
Markdown 源页面 markdown-usage.md 使用标准 Markdown 语法（一级/二级标题、列表、java 围栏代码块、行内链接），此处不赘述。
3.4 构建与验证
执行干净构建：
$ cd /opt/doxia/demo && mvn -B clean site
[INFO] Scanning for projects...
[INFO] Rendering 5 site documents ...
[INFO] Generating "Summary" report --- maven-project-info-reports-plugin:3.9.0:summary
[INFO] Generating "Project Information" report --- maven-site-plugin:3.21.0:project-info
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.541 s
输出节选（实测首尾）：首部为工程扫描与文档渲染日志，尾部为两个报告生成与构建成功标志；首次构建含插件下载约 45 秒，缓存后全量 2.5 秒。产物验证回显：
$ ls /opt/doxia/demo/target/site/
apt-usage.html css dependency-info.html fonts images img
index.html js markdown-usage.html plugin-management.html
plugins.html project-info.html summary.html
$ grep -o "<title>[^<]*</title>" target/site/index.html target/site/apt-usage.html target/site/markdown-usage.html
target/site/index.html:<title>Doxia 站点首页 – Doxia Site Demo</title>
target/site/apt-usage.html:<title>APT 用法 – Doxia Site Demo</title>
target/site/markdown-usage.html:<title>Markdown 用法 – Doxia Site Demo</title>
$ grep -c "Hello Doxia" target/site/index.html
1
$ grep -c "Hello Markdown" target/site/markdown-usage.html
1
三个验证点全部通过：APT 标题块正确注入 HTML title；两种格式的代码块原样保留；APT 表格页 apt-usage.html 中含 <table class="table table-bordered table-striped"> 且中文单元格内容完整。
3.5 构建日志中的迁移告警
3.21.0 每次构建都会打印如下告警，实测原文：
[WARNING] Site model of 'com.example:doxia-site-demo:jar:1.0.0' for default locale is
still using the old pre-version 2.0.0 model. You MUST migrate to the new model as soon
as possible otherwise your build will break in the future!
[WARNING] No project URL defined - site links will not be relativized!
解读：装饰模型 2.0.0 迁移是官方明确的未来破坏性变更方向，现有 1.8.0 命名空间仍可用但会持续告警；第二条告警提示在 POM 中补充 url 可让站内相对链接正确折叠。本文保留 1.8.0 模型完成全部实测。
四、doxia-converter 格式互转实战
4.1 下载与构建
$ cd /opt/doxia && curl -sSL -o doxia-converter-1.3-source-release.zip \
https://dlcdn.apache.org/maven/doxia/doxia-converter-1.3-source-release.zip
$ ls -la doxia-converter-1.3-source-release.zip
-rw-r--r-- 1 root root 77813 Oct 14 16:54 doxia-converter-1.3-source-release.zip
$ sha512sum doxia-converter-1.3-source-release.zip
fd82c96acd5bd8bc2dd84127d1c2143df57166f04bf0ac47f5d1b99728fe701126be4f1304388f6003fe81970bb4a9591f22b55eeece5023750d511d5b007aaf doxia-converter-1.3-source-release.zip
$ unzip -q doxia-converter-1.3-source-release.zip
$ cd doxia-converter-1.3 && mvn -B package -DskipTests
[INFO] Building jar: /opt/doxia/doxia-converter-1.3/target/doxia-converter-1.3-jar-with-dependencies.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:57 min
输出节选（实测首尾）：下载包 77813 字节，SHA-512 全值如上；构建产出两个 JAR——36 万字节级的瘦包 doxia-converter-1.3.jar 与 35323472 字节的胖包 jar-with-dependencies，运行时用胖包。构建一次成功，无 JDK 17 兼容问题。
4.2 能力清单确认
$ java -jar target/doxia-converter-1.3-jar-with-dependencies.jar --help
usage: doxia-converter [-e] [-f] [-from <arg>] [-h] [-in <arg>] [-inEncoding <arg>]
[-out <arg>] [-outEncoding <arg>] [-to <arg>] [-v] [-X]
Options:
-from <arg> From format. If not specified, try to autodetect it.
-in,--input <arg> Input file or directory.
-out,--output <arg> Output file or directory.
Supported Formats:
from: apt, confluence, docbook, fml, markdown, twiki, xdoc, xhtml, xhtml5 or autodetect
to: apt, confluence, docbook, fo, itext, latex, markdown, rtf, twiki, xdoc, xhtml, xhtml5
参数逐项说明：-in/-out 支持文件或目录；-from 可省略由内容自动探测；-e 开启错误堆栈便于排障；-f 仅对 XML 类输出做美化缩进。
4.3 APT 转 Markdown 实测
$ cd /opt/doxia && java -jar doxia-converter-1.3/target/doxia-converter-1.3-jar-with-dependencies.jar \
-in demo/src/site/apt/apt-usage.apt -from apt -to markdown -out /tmp/apt-usage-conv.md -e
$ cat /tmp/apt-usage-conv.md
title: APT 用法
author: zhou
date: 2026-10-15
演示表格：
|格式|扩展名|说明|
|---|---|---|
|APT Markdown Xdoc|.apt .md .xml|原生格式 通用格式 XML 格式|
演示引用与链接：参见 [Doxia 官网](https://maven.apache.org/doxia/)。
实测结论：标题块三要素正确转成 YAML 风格头；APT 链接语法转成了标准 Markdown 链接；表格是已知弱项——APT 表格的多列单元格被合并进同一列单元格，转换后需要人工修复表格。这符合"Sink 事件流表达能力有限"的架构现实，务必人工复核表格转换结果。
4.4 Markdown 转 APT 实测
$ java -jar doxia-converter-1.3/target/doxia-converter-1.3-jar-with-dependencies.jar \
-in demo/src/site/markdown/markdown-usage.md -from markdown -to apt -out /tmp/markdown-usage-conv.apt -e
[warn] [Apt Sink] Unknown Sink event: 'h1', ignoring!
[warn] [Apt Sink] Unknown Sink event: 'h1', ignoring!
$ cat /tmp/markdown-usage-conv.apt
-----
Markdown 用法
-----
-----
-----
Markdown 用法
本页面演示 Doxia 的 Markdown 支持。
列表示例
* 第一项
* 第二项
[]
代码示例
+------+
<<<public class Demo \{
public static void main(String\[\] args) \{
System.out.println("Hello Markdown");
\}
\}
>>>
+------+
链接示例
参见 {{{https://maven.apache.org/doxia/}Doxia 官网}}。
实测结论与逐项解读：Markdown 元信息进入 APT 标题块；## 二级标题转成列 0 纯文本行（正确对应 APT 一级章节）；Markdown 的 h1 级事件在 AptSink 中无对应事件，打印 Unknown Sink event 告警并忽略（页面标题已由标题块承载，无实际损失）；Java 代码块正确落入 +------+ 围栏并用 APT 行内原样语法 <<< >>> 包裹，大括号与方括号做了转义；链接转为 APT 双花括号语法。
4.5 APT 转 XHTML5 实测
$ java -jar doxia-converter-1.3/target/doxia-converter-1.3-jar-with-dependencies.jar \
-in demo/src/site/apt/index.apt -from apt -to xhtml5 -out /tmp/index-conv.html -e
$ head -6 /tmp/index-conv.html
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Doxia 站点首页</title><meta name="author" content="zhou" /><meta name="date" content="2026-10-15" /><meta charset="UTF-8"/></head>
<body>
<p>这是一个通过 <a class="externalLink" href="https://maven.apache.org/doxia/">Apache Doxia</a> 渲染的 APT 页面。</p><section>
<h2>小节标题</h2>
输出节选（实测首部）：XHTML5 输出把 APT 标题块转为 title 与 meta 标签，外链加 externalLink 类，章节降为 section/h2 结构。此链路可作为"APT 遗留页面上 HTML5"的最小方案。
五、进阶用法
5.1 导航菜单与横幅定制
site.xml 的 body/menu 支持多组菜单与 item 嵌套，item 可用 href 指向外部链接或站内页面；bannerLeft/bannerRight 分别定义左右横幅。实测中文菜单名在 fluido 皮肤下正常渲染无乱码。
5.2 目录批量转换
-in 与 -out 都传目录即可批量转换，实测命令形态：
java -jar doxia-converter-1.3-jar-with-dependencies.jar \
-in /opt/doxia/batch-apt -from apt -to markdown -out /opt/doxia/batch-md
批量模式按目录树平铺输出，单文件失败不影响其余文件，结束后以退出码反映整体结果，适合脚本化迁移。省略 -from 时按内容自动探测格式，但混有 XML 类内容时建议显式指定以免误判。
5.3 编码控制
-inEncoding/-outEncoding 显式指定输入输出编码，帮助文档列出的支持编码含 UTF-8、GB18030、Big5、windows-1251 等。中文遗留内容常见的 GB18030 输入场景可按 java -jar 转换器.jar -in 旧文档.apt -inEncoding GB18030 -to markdown -out 新文档.md 使用。
5.4 增量构建的注意点
实测发现 maven-site-plugin 有源文件未变化即跳过再生的机制：若上次构建异常中断留下 0 字节 HTML，源码未改时直接重跑不会修复，需 mvn clean site 全量重建。本文 3.4 节的构建即 clean 后的产物。
六、常见问题（FAQ）
Q1：站点构建报 skin cannot be null 怎么解决？ A：在 site.xml 显式添加 skin 节点。实测 maven-site-plugin 3.21.0 不再有默认皮肤，必须指定，且要选兼容 2.x 管线的 maven-fluido-skin（当前 2.1.0）。
Q2：皮肤已配置仍报 Skin does not contain template at META-INF/maven/site.vm？ A：说明用了旧版皮肤（如 maven-default-skin 1.3）。实测该皮肤最新 1.3 只含旧模板路径，与 3.21.0 不兼容；换 maven-fluido-skin 2.1.0 即可。
Q3：APT 文件构建报 expected SECTION1, found SECTION2？
A：APT 的一级章节是列 0 纯文本行，* 前缀已是二级。检查是否按 Markdown 习惯写了 * 一级标题；把一级章节改为纯文本行、层级依次递增即可。
Q4：APT 标题块为什么不生效，标题全挤在正文里？
A：标题块的分隔行 ------ 必须缩进（至少一个空格）。实测列 0 的分隔行会被当作普通内容，标题、作者、日期就无法注入 HTML 的 title/meta。官方测试文件 test.apt 也是缩进写法。
Q5：转换 Markdown 到 APT 时大量 Unknown Sink event: h1 告警？
A：这是 AptSink 不支持 h1 事件导致的告警，正文标题信息已由 APT 标题块承载，可忽略；若在意日志干净，可把 Markdown 源文件直接用 ## 起始，避免 h1 事件。
Q6：APT 表格转 Markdown 后列都挤在一起了？ A：实测确认是当前版本转换器的已知弱项，多列单元格被合并。建议转换后人工修表格，或改走 APT 转 XHTML5 链路保留表格结构。
Q7：构建成功但某个页面是 0 字节？
A：增量构建跳过了异常残留页面的重建。执行 mvn clean site 全量重建即可，本文实测 clean 全量构建 2.5 秒完成。
Q8：converter 需要安装 Maven 吗？ A：构建 converter 时需要 Maven，但日常使用不需要：把构建产物 jar-with-dependencies（35323472 字节）拷贝到任何有 Java 17 的机器上，java -jar 直接运行。
Q9：中文源页面输出乱码怎么办？ A：三处统一为 UTF-8 即可：POM 的 sourceEncoding、文件本身编码、converter 的 -inEncoding/-outEncoding。实测 UTF-8 全链路中文标题、菜单、表格内容均正常。
七、参考链接
- maven-site-plugin 官方文档：https://maven.apache.org/plugins/maven-site-plugin/
- Doxia 官网：https://maven.apache.org/doxia/
- doxia-converter 发行页：https://dlcdn.apache.org/maven/doxia/
- APT 语法参考：https://maven.apache.org/doxia/references/apt-format.html
- Fluido Skin：https://maven.apache.org/skins/maven-fluido-skin/
- Maven Site 阶段说明（site 目标生命周期）：https://maven.apache.org/plugins/maven-site-plugin/usage.html