這是我最近開發的一個基于 Jenkins Pipeline 的 DITA 文檔自動化構建方案。對于需要維護大量 DITA 格式文檔的團隊來說，手動構建不僅效率低下，還容易出現版本不一致的問題。通過這套開源方案，我們可以實現代碼拉取、多地圖并行構建、結果歸檔與報告發布的全流程自動化，希望能幫到有類似需求的程序猿，在看之前可以去了解一下 GitHub Actions。

為什么需要 DITA 文檔自動化構建？

DITA（Darwin Information Typing Architecture）作為一種基于 XML 的文檔結構化標準，廣泛用于技術文檔、用戶手冊等場景。但手動執行 DITA-OT（DITA Open Toolkit）構建命令存在不少痛點：

• 重復勞動：每次代碼更新都需要手動觸發構建
• 效率低下：多份文檔需依次構建，耗時較長
• 環境不一致：不同開發者本地環境路徑、配置差異可能導致構建失敗
• 結果難追溯：構建產物分散，不方便團隊共享查看

而通過 Jenkins Pipeline 自動化構建，能完美解決這些問題 —— 統一環境、自動觸發、并行構建、集中管理產物，大幅提升團隊協作效率。

方案準備：環境與工具

在開始前，我們需要準備這些基礎組件：

1. 基礎環境

   • 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，就要去官網下載）

2. 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. 執行與驗證

1. 點擊任務頁面的 “Build Now” 手動觸發第一次構建，在 “控制臺輸出” 中查看實時日志，確認各階段是否正常執行。
2. 構建成功后，可在左側 “HTML reports” 中查看生成的 HTML 文檔，在 “Artifacts” 中下載 PDF 文件。

注意事項（避坑指南）

1. 路徑正確性：DITA_OT、MAP_DIR等路徑需根據實際環境修改（Windows 用\，Linux/macOS 用/）。
2. 項目結構：確保倉庫目錄結構與腳本一致（map 目錄放.ditamap，pdf/html 目錄放自定義模板）。
3. 權限問題：Jenkins 服務需有訪問 JDK、DITA-OT 目錄及代碼倉庫的權限（團隊則聯系管理員配置）。
4. 并行構建資源：若地圖文件過多，并行構建可能消耗較多資源，可根據服務器性能調整并行數量。

總結

這套基于 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 文檔自動化構建與發布（開源方案）》）。