当前位置：首页 > news >正文

基于 Jenkins Pipeline 实现 DITA 文档自动化构建与发布（开源方案）

news 2025/8/11 13:25:52

这是我最近开发的一个基于 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，这是自动化流程的核心脚本。以下是完整脚本及关键步骤解析：

pipeline {agent anyenvironment {// 配置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: truearchiveArtifacts 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. 版权归属

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 文档自动化构建与发布（开源方案）》）。

查看全文

http://www.xdnf.cn/news/1252351.html