这是我最近开发的一个基于 Jenkins Pipeline 的 DITA 文档自动化构建方案。对于需要维护大量 DITA 格式文档的团队来说，手动构建不仅效率低下，还容易出现版本不一致的问题。通过这套开源方案，我们可以实现代码拉取、多地图并行构建、结果归档与报告发布的全流程自动化，希望能帮到有类似需求的程序猿，在看之前可以去了解一下 GitHub Actions。
为什么需要 DITA 文档自动化构建？
DITA（Darwin Information Typing Architecture）作为一种基于 XML 的文档结构化标准，广泛用于技术文档、用户手册等场景。但手动执行 DITA-OT（DITA Open Toolkit）构建命令存在不少痛点：
- 重复劳动：每次代码更新都需要手动触发构建
- 效率低下：多份文档需依次构建，耗时较长
- 环境不一致：不同开发者本地环境路径、配置差异可能导致构建失败
- 结果难追溯：构建产物分散，不方便团队共享查看
而通过 Jenkins Pipeline 自动化构建，能完美解决这些问题 ------ 统一环境、自动触发、并行构建、集中管理产物，大幅提升团队协作效率。
方案准备：环境与工具
在开始前，我们需要准备这些基础组件：
-
基础环境
- JDK 17（DITA-OT 运行依赖，需记录安装路径）
- Oxygen XML Editor（内置 DITA-OT，需找到其
DITA-OT目录路径，通常在Oxygen XML Editor X.X\frameworks\dita\DITA-OT） - DITA-OT（如果你的 OXE 木有内置的 DITA-OT，就要去官网下载）
-
Jenkins 插件（前提先有 Jenkins）
需管理员（如果你是个人，那你就一个人整吧）在 Jenkins 中安装以下插件（均为开源插件，可从 Jenkins 官方仓库获取）：
- Git Plugin：用于从远程仓库拉取 DITA 文档代码
- Pipeline：支持编写自动化脚本（Jenkinsfile）
- HTML Publisher Plugin：发布构建生成的 HTML 文档，方便在线查看
step-by-step：从零搭建自动化流程
1. Jenkins 全局配置
首先让管理员（如果你是个人，那你就一个人整吧）配置 JDK 17（全局工具配置 ）：
进入 Jenkins 首页 → 系统管理 → 全局工具配置 → JDK，添加 JDK 17 并填写安装路径。建议团队统一 JDK 路径，后续可共用 Jenkinsfile，避免路径适配问题。
2. 创建 Pipeline 任务
在 Jenkins 中新建任务，选择 "Pipeline" 类型，然后配置源代码管理：
- 进入任务配置 → Pipeline 部分 → Definition 选择 "Pipeline script from SCM"
- SCM 选择 Git，填写远程仓库地址（例如
https://github.com/your-repo/dita-docs.git），并指定分支（如 main）
3. 核心：编写 Jenkinsfile（开源脚本）
在代码仓库根目录创建Jenkinsfile，这是自动化流程的核心脚本。以下是完整脚本及关键步骤解析：
Groovy
pipeline {
agent any
environment {
// 配置Oxygen内置DITA-OT路径（根据实际环境修改）
DITA_OT = 'C:\\...\\DITA-OT'
// DITA地图文件（.ditamap）所在目录
MAP_DIR = './map'
// PDF自定义模板路径
PDF_TEMPLATE = './pdf/custom.xsl'
// HTML自定义样式路径
HTML_CSS = './html/custom.css'
}
stages {
stage('Checkout') {
steps {
// 从远程仓库拉取最新代码
git branch: 'main', url: 'https://github.com/your-repo/dita-docs.git'
}
}
stage('Discover Maps') {
steps {
script {
// 自动发现所有.ditamap文件（支持子目录）
def mapFiles = bat(script: 'dir /b /s %MAP_DIR%\\*.ditamap', returnStdout: true).trim().split('\r\n')
// 存储地图文件列表到环境变量，供后续阶段使用
env.MAP_FILES = mapFiles.join(',')
echo "找到 ${mapFiles.size()} 个DITA地图文件"
// 打印发现的地图文件（调试用）
for (mapFile in mapFiles) {
echo "地图文件: ${mapFile}"
}
}
}
}
stage('Build All Maps') {
parallel {
// 并行构建每个地图文件（提升效率）
script {
def mapFiles = env.MAP_FILES.split(',')
def parallelStages = [:]
for (mapFile in mapFiles) {
// 提取地图文件名（用于输出目录命名）
def mapName = mapFile.tokenize('\\')[-1].replace('.ditamap', '')
parallelStages[mapName] = {
stage("Build ${mapName}") {
steps {
echo "开始构建地图: ${mapFile}"
// 创建PDF和HTML输出目录
bat "mkdir output\\${mapName}\\pdf"
bat "mkdir output\\${mapName}\\html"
// 构建PDF文档（使用自定义模板）
bat """
${DITA_OT}\\bin\\dita.bat -i ${mapFile} -f pdf
-o output\\${mapName}\\pdf
-Dargs.xsl.custom=${PDF_TEMPLATE}
"""
// 构建HTML5文档（使用自定义样式）
bat """
${DITA_OT}\\bin\\dita.bat -i ${mapFile} -f html5
-o output\\${mapName}\\html
-Dargs.css=${HTML_CSS}
"""
// 归档构建产物（PDF和HTML）
archiveArtifacts artifacts: "output/${mapName}/pdf/*.pdf", fingerprint: true
archiveArtifacts artifacts: "output/${mapName}/html/**/*", fingerprint: true
}
}
}
}
return parallelStages
}
}
}
stage('Publish Reports') {
steps {
script {
def mapFiles = env.MAP_FILES.split(',')
for (mapFile in mapFiles) {
def mapName = mapFile.tokenize('\\')[-1].replace('.ditamap', '')
// 发布HTML报告到Jenkins，方便在线查看
publishHTML([
allowMissing: true,
alwaysLinkToLastBuild: true,
keepAll: true,
reportDir: "output/${mapName}/html",
reportFiles: 'index.html',
reportName: "HTML: ${mapName}",
reportTitles: mapName
])
}
}
}
}
}
post {
success {
echo '所有地图构建成功！'
}
failure {
echo '至少有一个地图构建失败！'
}
}
}脚本关键步骤解析：
- 环境变量（environment）：集中配置路径信息，后续修改只需改这里，方便维护。
- Checkout 阶段：拉取远程仓库最新代码，确保构建基于最新内容。
- Discover Maps 阶段：自动扫描所有.ditamap 文件，无需手动指定，支持文档数量动态变化。
- Build All Maps 阶段：通过并行（parallel）构建多个地图文件，大幅缩短总耗时；同时生成 PDF 和 HTML 两种格式，并使用自定义模板和样式。
- Publish Reports 阶段：将 HTML 结果发布到 Jenkins，团队成员可直接在 Jenkins 页面查看，无需下载。
- post 部分：构建结束后输出结果状态，方便快速判断是否成功。
4. 配置自动触发
为了实现 "代码更新后自动构建"，可在 Jenkins 任务配置中设置定时检查：
- 进入任务配置 → Build Triggers → 勾选 "Build periodically"
- 填写 Cron 表达式，例如
*/30 * * * *（每 30 分钟检查一次代码更新，有变化则触发构建）。
5. 执行与验证
- 点击任务页面的 "Build Now" 手动触发第一次构建，在 "控制台输出" 中查看实时日志，确认各阶段是否正常执行。
- 构建成功后，可在左侧 "HTML reports" 中查看生成的 HTML 文档，在 "Artifacts" 中下载 PDF 文件。
注意事项（避坑指南）
- 路径正确性 ：
DITA_OT、MAP_DIR等路径需根据实际环境修改（Windows 用\，Linux/macOS 用/）。 - 项目结构：确保仓库目录结构与脚本一致（map 目录放.ditamap，pdf/html 目录放自定义模板）。
- 权限问题：Jenkins 服务需有访问 JDK、DITA-OT 目录及代码仓库的权限（团队则联系管理员配置）。
- 并行构建资源：若地图文件过多，并行构建可能消耗较多资源，可根据服务器性能调整并行数量。
总结
这套基于 Jenkins Pipeline 的 DITA 文档自动化方案完全开源，核心脚本（Jenkinsfile，使用 Groovy 写的声明式流水线脚本）可直接复用并根据团队需求修改。通过自动化构建，我们能减少 80% 的手动操作，同时保证文档构建的一致性和可追溯性。
如果你的团队也需要实现 DITA 文档发布自动化，不妨试试这个方案，欢迎在评论区交流改进建议！
开源声明
1. 许可证说明
本文中提供的 Jenkins Pipeline 脚本（Jenkinsfile）、自动化流程设计及相关配置示例，采用 MIT License 开源。
你可以自由地：
- 复制、使用、修改本方案的代码和流程；
- 将本方案用于个人、商业或开源项目；
- 分发或二次开发本方案的衍生作品。
前提条件 ：在所有副本或重要衍生部分中，需保留原始版权声明和本许可证说明。
MIT 许可证全文可参考：The MIT License -- Open Source Initiative
2. 版权归属
© 2025 作者：Allenliu_Andy。
本文及包含的代码示例、流程设计等内容的版权归作者所有，未经许可不得擅自移除或修改本版权声明。
3. 免责声明
本方案及代码仅为示例参考，基于特定技术环境（JDK 17、Oxygen XML Editor、Jenkins 及插件等）开发。尽管已尽力确保内容的准确性和可用性，但不对以下内容做任何明示或暗示保证：
- 方案在所有环境中的兼容性；
- 代码无缺陷或错误；
- 使用本方案产生的任何直接 / 间接结果（如数据丢失、业务影响等）。
使用提示：在生产环境使用前，请务必根据自身场景测试验证，作者不对因使用本方案导致的任何损失承担责任。
4. 第三方依赖说明
本方案的实现依赖以下开源工具 / 组件，其使用需遵循各自的开源许可证：
- Jenkins 及插件 （Git Plugin、Pipeline、HTML Publisher Plugin 等）：遵循 MIT License；
- DITA-OT（DITA Open Toolkit） ：遵循 Apache License 2.0；
- Oxygen XML Editor ：本文仅涉及对其内置 DITA-OT 的路径引用，其软件许可请参考 Oxygen 官方条款。
使用本方案即表示你同意遵守上述第三方工具的许可条款。
5. 贡献与引用规范
- 欢迎通过 issue 或代码提交提出改进建议，所有贡献内容将默认采用与本方案相同的 MIT License 授权；
- 若将本方案或代码用于公开文档、项目或产品中，请注明原始来源（如：参考自 Allenliu_Andy 的《基于 Jenkins Pipeline 实现 DITA 文档自动化构建与发布（开源方案）》）。