知識與實務

商業實務・AI 應用・人才發展

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 個文件情境與常見錯誤修正表。

專題編輯 Derek Chou

同一份課程講義,網站要 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
Pandoc 單一來源流程圖:Markdown 主檔、defaults 設定、Lua filters、輸出 DOCX/HTML/PDF、逐格式檢查
Pandoc 單一來源的多格式輸出流程

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 內的圖片另存到指定資料夾。

官方資料來源

圖片為原創示意圖。

延伸閱讀與企業實作

講義、SOP 或產品手冊若同時要網頁版與 Word 版,可以挑一份正在維護的文件,和天地人一起規劃 Markdown 主檔、樣式模板與自動輸出流程,並決定哪些格式需要人工版面檢查。團隊若需要先熟悉 Markdown 與版本管理,也能安排數位工具內訓,以自己的文件當練習素材。

企業 AI 導入陪跑|Excel 與數位工具企業內訓|企業內訓課程規劃

AI 生成內容

本文由 TARAISG(TIANDIREN AI SOLUTION GROUP)使用 AI 模型產生正文、整理來源並設計實務工具。方法依據與限制列於文末;案例為明確標示的教學假設。未有具名紀錄時,不宣稱經人工或專家審核。

查看內容製作與更正說明

TIANDIREN INSIGHTS

接著可以閱讀什麼?

TIANDIREN INSIGHTS

延伸你的下一步閱讀

立即領!558元學習投資折抵金

能力投資季。立即領取 558 元學習金!全站線上課立即折抵。只需填寫 Email,即可輕鬆獲得,先領起來,不要錯過!

立即領!559元學習投資折抵金

能力投資季。立即領取 559 元學習金!全站線上課立即折抵。只需填寫 Email,即可輕鬆獲得,先領起來,不要錯過!

立即領!579 元學習金

學習,看見新可能。 10/14 前領取 579 元折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

立即領!599 元學習金

學習,帶來新可能。 09/09 前領取 558 元折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

立即領!558 元學習金

學習,發現新大陸。 8/29 前領取 558 元折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

立即領!559 元學習金

學習,連結新亮點。 8/14 前領取 559 元折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

立即領!555 元學習金

學習,發現更多視角。 6/14 前領取 555 元折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

立即領!556 元學習金

學習,累積無限可能。 5/29 前領取 556 元折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

立即領!557 元學習金

學習,讓我們發現未曾想像的可能!5/14 前領取 557 元折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

立即領!579 元折抵金

知識就是力量,專業成就未來!3/18 前領取 579 元課程折抵金,解鎖數百堂高品質線上課程,提升職場競爭力與專業技能。只需填寫Email,即可輕鬆獲得,投資自己從現在開始!

年終學習金

年終之餘用學習投資自己!填入 Email ,立即領取 588 元年終學習金!數百堂線上課程立即折抵,先領取收藏起來!