Apache Maven Doxia 2.1.0 格式与配置详解

目标：掌握 Doxia 2.1.0 站点配置三层体系、site.xml 装饰模型与 APT/Markdown 等源格式语法的实测行为与默认值，已在 Ubuntu 22.04 实测通过。

一、环境信息

本文所有"默认值"均指该组合下的实测行为：配置项的生效与否以构建结果与产物 HTML 为准，不做文档转述。

二、配置体系总览

Doxia 站点的配置分三层，自上而下作用：

三层解说：构建层决定"用哪个版本的引擎"；装饰层决定"站点长什么样"；内容层决定"每页写了什么"。实测排障顺序也应自上而下——插件报错看 pom，皮肤与导航问题看 site.xml，页面内容渲染异常看源格式语法。

三、构建层配置：maven-site-plugin 关键项

3.1 插件声明与版本

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.21.0</version>
</plugin>

逐项说明：groupId/artifactId 固定；version 必须显式钉住，3.21.0 是绑定 Doxia 2.x 管线的现行版，实测与 JDK 17、Maven 3.6.3 兼容良好。

3.2 实测默认行为清单

表格逐项备注：报告聚合是 Doxia 区别于一般静态站点生成器的核心能力，依赖、SCM、团队等信息自动成页；皮肤必填是 2.x 最容易踩的行为变更；增量跳过机制在构建被强杀后可能留下 0 字节页面，clean site 全量重建实测 2.5 秒，成本可忽略。

四、装饰层配置：site.xml 详解

4.1 可用元素与实测默认值

4.2 实测生效的 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（实测可用，构建输出迁移告警但功能完整）；name 会拼进每个页面 title，实测产物为"页面标题 – Doxia Site Demo"三段式；skin 三元组从仓库拉取皮肤 JAR，实测错误版本号会直接构建失败（如 fluido-skin 不存在 1.3 版时报 Could not find artifact）；menu/item 生成本文实测站点的三项目左侧导航，中文名渲染正常。

4.3 装饰模型 2.0.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!

解读：官方明确 1.8.0 装饰模型处于弃用通道，生产环境应规划迁移；第二条告警在 POM 补充 project/url 后可消除。本文按 1.8.0 完成全部实测，功能无缺失。

五、内容层配置：源格式分类详解

5.1 格式选择一览

💡 技术拓展：四种格式并非互斥，站点可混用——本文实测项目同时挂 APT 与 Markdown 页面且共用一套导航。选择建议：新写文档用 Markdown，需要复杂表格或迁移既有 APT 库存用 APT，FAQ 页用 FML，程序化产页用 Xdoc。本文以 APT 与 Markdown 为实测对象。

5.2 APT 语法实测详解

标题块（页元信息）：四个分隔行夹住标题、作者、日期。实测分隔行必须缩进：

 ------
 页面标题
 ------
 作者名
 ------
 2026-10-15
 ------

实测行为：缩进的分隔行被识别为标题块，标题注入 HTML title，作者与日期注入 meta；分隔行写在列 0 时不构成标题块，内容被当普通文本解析。

章节层级：实测规则与 Markdown 相反——列 0 纯文本行是一级章节，* 是二级，** 是三级，最多五级。层级不按序递增时构建失败，实测报错 AptParseException: expected SECTION1, found SECTION2。

正文段落：缩进一到三格的文本为段落，实测两格最常用；段落内空行分段。

列表：缩进的 * 为无序列表项，实测可嵌套；有序列表以 [[1]]、[[2]] 标记列表项起始数字。

表格：实测语法与渲染结果（apt-usage.apt 片段）：

*----------+----------+----------+
| 格式     | 扩展名   | 说明     |
*----------+----------+----------+
| APT      | .apt     | 原生格式 |
| Markdown | .md      | 通用格式 |
| Xdoc     | .xml     | XML 格式 |
*----------+----------+----------+

实测产物 HTML 中表格带 table-bordered table-striped 样式类，中文单元格完整；行首星号表示表头行，加号列分隔，竖线包单元格。

代码块：+---+（至少三个加号与三个减号）围栏，内部原样输出，实测 Java 代码缩进与引号完整保留。

链接与锚点：{{{URL}文字}} 外链、{{{page.html}文字}} 站内链接、{锚点} 自定义锚点。实测外链渲染为 class="externalLink" 的 a 标签。

字体标注：<<原文>> 为等宽强调、__下划线__ 为斜体/下划线变体，实测 APT 转换器输出中代码片段以 <<< >>> 形式回写。

5.3 Markdown 支持范围实测

实测 markdown-usage.md 覆盖以下元素全部正常渲染：一级/二级标题（映射 h1/h2，页面标题同时进 title）、无序列表、java 围栏代码块（原样保留）、行内链接、普通段落。反向转换（Markdown 转 APT）实测细节见实战篇——h1 事件在 AptSink 无对应映射，输出告警 Unknown Sink event: h1 并忽略。

5.4 Xdoc 与 FML 速览

Xdoc 是 XML 格式的页面描述（根元素 document/section 等），实测 2.1.0 的 doxia-module-xdoc 仍在核心发行内；FML（FAQ Markup Language）以 faqs/faq 问答对组织内容，适合构建 FAQ 页并可与站点的 FAQ 报告联动。两者均由 XML 解析器处理，语法错误会在构建期直接暴露，这是 XML 类格式的门禁优势。

六、生产模板

6.1 最小可用生产组合

以下三份配置即本文实测通过的完整组合，可直接复用。

POM 关键段（构建层）：

<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>
  </plugins>
</build>

站点描述符（装饰层）：见 4.2 节模板，替换 name 与菜单项即可。

镜像加速（/root/.m2/settings.xml，构建层配套）：

<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>

6.2 上线前检查清单

七、常见问题（FAQ）

Q1：site.xml 里可以不写 skin 吗？ A：实测 3.21.0 不允许，缺失时报 skin cannot be null 构建失败。这是 2.x 管线与旧版的显著差异，皮肤必须显式声明。

Q2：maven-default-skin 和 maven-fluido-skin 怎么选？ A：实测 default-skin 停在 1.3 且缺新渲染模板（报 Skin does not contain template at META-INF/maven/site.vm），3.21.0 下必须用 fluido-skin 2.1.0。生产环境直接钉 fluido。

Q3：APT 章节的正确层级写法是什么？ A：一级章节是列 0 纯文本行，二级用单星号，三级双星号，最多五级。层级跳档实测直接构建失败（expected SECTION1, found SECTION2）。

Q4：APT 标题块的作者、日期有什么用？ A：实测会被注入生成页的 meta 标签（author、date），并影响站点 Last Published 展示逻辑；省略作者行时构建仍通过，但建议保留以利追溯。

Q5：Markdown 页面能和 APT 页面共用导航吗？ A：能。实测同一 site.xml 的 menu 同时挂两类页面，产物 HTML 中中文名正常渲染。站点级导航与源格式无关。

Q6：APT 表格怎么写表头？ A：行首用星号的分隔行即表头行（实测 *---+--- 格式），其余数据行用竖线包裹。注意转换器反向输出 Markdown 时表格列会合并，需人工修复。

Q7：如何消除 pre-version 2.0.0 model 迁移告警？ A：将 site.xml 命名空间升级到 DECORATION 2.0.0 模型。本文实测保留 1.8.0 亦能完成全部功能，迁移属前瞻性要求；另建议在 POM 补 url 消除第二条链接相对化告警。

Q8：报告页太多，能关掉一部分吗？ A：可以，在 POM 的 site 插件配置里用 reportPlugins/或迁移到报告聚合配置裁剪。实测默认探出 15 类报告（依赖、插件、SCM 等），未裁剪时这些页面全部生成于 target/site。

Q9：源文件改了但产物没变？ A：插件按源文件变更做增量跳过；若上次构建异常中断，先 mvn clean site 全量重建。实测 clean 后全量构建仅 2.5 秒。

Q10：中文内容乱码的三处排查点？ A：POM 的 project.build.sourceEncoding 设 UTF-8、源文件保存为 UTF-8、converter 场景加 -inEncoding/-outEncoding。三处一致后实测全链路无乱码。

八、参考链接

1. maven-site-plugin 配置文档：https://maven.apache.org/plugins/maven-site-plugin/
2. Site 插件装饰模型参考：https://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html
3. APT 语法官方参考：https://maven.apache.org/doxia/references/apt-format.html
4. FML 格式参考：https://maven.apache.org/doxia/references/fml-format.html
5. Xdoc 格式参考：https://maven.apache.org/doxia/references/xdoc-format.html
6. Fluido Skin 配置：https://maven.apache.org/skins/maven-fluido-skin/