AI 工作實務
Pandoc 教學:一份 Markdown 同時輸出 Word、HTML 與 PDF
Pandoc 如何讓講義、手冊只維護一份 Markdown?說明 reference-doc 樣式、defaults 設定檔、Lua filters、引用管理與中文 PDF 字型,搭配 8 個文件情境與常見錯誤修正表。

本文目錄
什麼時候該用 Pandoc?4 個技術重點:讓多格式輸出保持一致安裝與版本確認第一個可執行範例:一份 Markdown 輸出 HTML 與 Word8 個實務情境:從講義到知識庫常見錯誤、原因與修正上線前驗收清單常見問題官方資料來源延伸閱讀與企業實作Pandoc 如何讓講義、手冊只維護一份 Markdown?說明 reference-doc 樣式、defaults 設定檔、Lua filters、引用管理與中文 PDF 字型,搭配 8 個文件情境與常見錯誤修正表。
同一份課程講義,網站要 HTML、學員要 Word、印刷要 PDF,結果常常變成三份各改各的檔案。Pandoc 的做法是只維護一份 Markdown 主檔,再依需要輸出不同格式,內容與外觀分開管理。
本文說明 Pandoc 在企業文件流程中真正有用的功能:reference-doc 樣式模板、defaults 設定檔、Lua filters、引用管理與中文 PDF 引擎,並列出常見的轉換陷阱。範例都以 Pandoc 3.1 轉換過。
重點回答:Pandoc 是開源文件轉換工具,可把一份 Markdown 同時輸出 Word、HTML 與 PDF,適合講義與手冊。
什麼時候該用 Pandoc?
當同一份內容要以兩種以上格式交付,而且會持續改版,Pandoc 的價值最明顯。內容只改 Markdown,格式由模板負責,每次輸出都是同一個來源。
| 情況 | 建議做法 |
|---|---|
| 內容常改版、要多格式輸出 | Markdown 主檔+Pandoc |
| 一次性、版面極度講究的設計稿 | 直接用排版或設計軟體 |
| 多人用 Word 追蹤修訂審稿 | 審稿留在 Word,定稿再回寫 Markdown |
| 已有 GitHub 技術文件 | 用 -f gfm 讀入,接 CI 自動輸出 |
Pandoc 不是文書編輯器,也不會幫你判斷內容對錯。它處理的是「結構轉換」,所以來源的標題層級、表格和清單寫得越規矩,輸出越穩定。
4 個技術重點:讓多格式輸出保持一致
用語意寫內容,不要用空白排版
標題就用 #、##,不要用粗體假裝標題;表格用表格語法,不要用空白對齊。Pandoc 先把文件讀成內部的語法樹(AST),語意不清楚的內容到了 Word 或 HTML 就會失去結構。
Word 的樣式交給 reference-doc
DOCX 的字型、標題樣式和頁首頁尾,不寫在 Markdown 裡,而是放在一份參考文件。先用 pandoc -o ref.docx --print-default-data-file reference.docx 取得預設樣板,在 Word 裡修改「標題 1」「內文」等樣式後存檔,輸出時加上 --reference-doc=ref.docx。
HTML 則用 --css 指定樣式表,PDF 由 PDF 引擎與模板決定。三種格式各自有外觀層,彼此不互相干擾。
把參數寫進 defaults 檔
命令列參數一多,每個人執行的結果就會不同。Pandoc 支援用 YAML 寫 defaults 檔,透過 -d docx.yaml 載入,輸入格式、模板、filters 和輸出位置都固定在檔案裡,放進版本控管。
Lua filters 要有版本和測試
Lua filter 可以在轉換途中改寫 AST,例如統一圖說格式、替換內部連結或移除草稿段落。它很強大,但也代表一支 filter 可能悄悄改掉引用或表格,所以要和內容一起版控,並為改動規則寫測試樣本。
安裝與版本確認
Pandoc 官方提供 Windows、macOS 與 Linux 的安裝檔,Linux 也可用套件管理員安裝,但發行版內建的版本通常較舊。Pandoc 3 與 2.x 在部分選項上有差異,團隊應固定同一個版本,並在 defaults 檔旁記錄 pandoc --version 的結果。
只需要 DOCX 和 HTML 時,安裝 Pandoc 本身就夠了。要輸出 PDF,才需要另外安裝 TeX Live(提供 xelatex、lualatex)或 typst、WeasyPrint 等引擎,以及繁中字型。
第一個可執行範例:一份 Markdown 輸出 HTML 與 Word
這組命令用 Pandoc 3.1.11 跑過,HTML 與 DOCX 都能正常輸出。guide.md 換成你自己的檔案即可。
pandoc --version
pandoc -o ref.docx --print-default-data-file reference.docx
pandoc guide.md -f markdown -t html5 --standalone -o output/guide.html
pandoc guide.md -f markdown -t docx --reference-doc=ref.docx -o output/guide.docx若 YAML 前言設定 lang: zh-TW,Pandoc 3.1 會出現「Could not load translations for zh-TW」警告。這只表示沒有內建的繁中介面詞彙(例如「Table」的翻譯),不影響輸出。
需要 PDF 時,要先安裝 PDF 引擎。繁中文件常見做法是用 XeLaTeX 並指定中文字型:
pandoc guide.md --pdf-engine=xelatex -V CJKmainfont="Noto Serif CJK TC" -o output/guide.pdf
8 個實務情境:從講義到知識庫
這些情境是為說明單一來源流程而設計的示例,並非客戶專案紀錄。
情境 1:企業內訓講義
講義要同時有網頁版和可下載的 Word 版。Markdown 保留唯一正文,Word 用 reference-doc 控制樣式,網頁版用 CSS。
最常見的問題是講師直接改 Word,造成兩個版本內容分叉。規則要定清楚:內容修改只回到 Markdown,Word 檔每次重新產生。
情境 2:GitHub 上的技術文件
開發文件和程式碼一起提交時,要明確指定輸入格式。GitHub 使用 GFM 方言,和 Pandoc 預設的 Markdown 在表格、任務清單與註腳上處理不同,建議用 -f gfm 或列出需要的擴充功能。
在 CI 中加入轉換與死連結檢查,文件就能跟著每個版本自動更新。
情境 3:多型號產品手冊
同一套手冊要給不同型號的客戶。可以用 metadata 或 defaults 檔區分型號與版本,輸出檔名帶版本號。
圖片要跟著版本一起鎖定,否則新版手冊很容易引用到舊版截圖。不同客戶的保密資訊不要混在同一份來源。
情境 4:顧問研究報告的參考文獻
報告的引用來源用 BibTeX 或 CSL JSON 保存,輸出時加 --citeproc --bibliography refs.bib,再用 --csl 指定引用格式。
轉換不出錯,不代表引用都是真的。提交前仍要人工逐條核對一手來源,尤其是 AI 協助整理過的文獻清單。
情境 5:合約範本
法務核准的標準條款應視為受保護的來源,個案只在獨立檔案中記錄差異。Pandoc 在這裡只是出版工具,條款內容的判斷仍屬法務。
每次輸出保留來源檔的雜湊,日後才查得到某份合約是由哪一版範本產生。
情境 6:舊 Word 文件轉成網站文章
把舊 Word 文件轉成 HTML 前,先清理語意:真正的標題、清單和表格。轉出後檢查 H1/H2 層級、圖片 alt 與內部連結。
直接轉檔常把 Word 裡的手動格式一起帶進 HTML。轉 Word 時可加 --extract-media=media 把圖片獨立存出來,方便重新命名與壓縮。
情境 7:中英雙語課程
中英文講義共用章節結構,各自設定 lang metadata 與字型。中文 PDF 能否正常顯示,取決於 PDF 引擎與實際安裝的字型。
每個語系都要實際跑一次 PDF 並翻頁檢查。缺字型時中文會變成方框或空白,這在命令列上不會報錯。
情境 8:Word 審稿回流
編輯習慣在 Word 留修訂與註解。Pandoc 讀取 DOCX 時可用 --track-changes=accept、reject 或 all 決定如何處理修訂,但雙向轉換無法保證保留所有註解與樣式。
比較穩妥的做法是:審稿在 Word 完成,由編輯確認後再把定稿內容回寫 Markdown,不要用轉換結果直接覆蓋主檔。
常見錯誤、原因與修正
| 現象 | 常見原因 | 修正方式 |
|---|---|---|
| Word 標題沒有套用樣式 | 來源用粗體假裝標題 | 改用 # 標題語法 |
| PDF 中文變方框 | 未指定或未安裝中文字型 | 加 -V CJKmainfont 並確認字型存在 |
| 「pdflatex not found」 | 沒有安裝 PDF 引擎 | 安裝 TeX Live,或改用 typst、weasyprint |
| GitHub 表格轉壞 | Markdown 方言不同 | 用 -f gfm 讀入 |
| 每人輸出結果不同 | 參數散落在各自的命令 | 統一用 defaults 檔並版控 |
上線前驗收清單
- Markdown 主檔放在版本控管,Word 檔一律由主檔產生。
- 參數寫在 defaults 檔,所有人用同一份設定輸出。
- reference-doc、CSS 與 Lua filters 都有版本號。
- DOCX 檢查標題樣式與表格,HTML 檢查連結與圖片 alt,PDF 翻頁檢查中文字型與分頁。
- 每次輸出記錄 Pandoc 版本與來源檔雜湊。
常見問題
Pandoc 可以取代 Word 嗎?
不行。Pandoc 是格式轉換器,不是編輯器;它適合讓內容在不同格式間穩定流動,日常編輯仍要用文字編輯器或 Word。
為什麼 DOCX 轉得出來,PDF 卻失敗?
PDF 需要額外的引擎,例如 XeLaTeX、LuaLaTeX、typst 或 WeasyPrint。DOCX 能輸出,不代表系統已安裝 PDF 引擎與中文字型。
Pandoc 適合接 GitHub Actions 嗎?
適合。純文字來源可以審查差異、版本化並自動產生檔案,但輸出後仍要保留人工版面檢查。
Word 轉 Markdown 會保留圖片嗎?
會轉出圖片連結,加上 --extract-media 參數可以把 DOCX 內的圖片另存到指定資料夾。
官方資料來源
圖片為原創示意圖。
延伸閱讀與企業實作
- LibreOffice 批次轉 PDF 怎麼做?headless 命令、字型跑版與驗收清單
- 新人一直問、老員工反覆教:企業該先整理 SOP,還是建立 AI 知識庫?
- GitHub Actions CI 實作:讓 Node.js PR 跑真測試,驗證錯誤變更會讓測試失敗
講義、SOP 或產品手冊若同時要網頁版與 Word 版,可以挑一份正在維護的文件,和天地人一起規劃 Markdown 主檔、樣式模板與自動輸出流程,並決定哪些格式需要人工版面檢查。團隊若需要先熟悉 Markdown 與版本管理,也能安排數位工具內訓,以自己的文件當練習素材。
本文由 TARAISG(TIANDIREN AI SOLUTION GROUP)使用 AI 模型產生正文、整理來源並設計實務工具。方法依據與限制列於文末;案例為明確標示的教學假設。未有具名紀錄時,不宣稱經人工或專家審核。
查看內容製作與更正說明