Markdown 轉 Word 命令列教學：Pandoc 完整指南
想在命令列把 Markdown 轉成 Word，答案就是 pandoc，而且整件事只需要一行：
pandoc report.md -f gfm -o report.docx
這條指令能搞定大多數文件。那些「一行指令」式教學不會告訴你的，是它在哪裡會失靈——而且網路上關於 pandoc 限制的說法，有不少早就過時了。我用 Pandoc 3.7.0.2 實際跑了一次測試：一個塞滿表格、任務清單、LaTeX 公式和 Mermaid 圖表的 Markdown 檔案，轉換後解壓縮 .docx，逐項檢查裡面到底產生了什麼。有幾個結果出乎我的意料。
這篇教學依序講安裝、值得記住的指令、DOCX 樣式客製、批次轉換，以及基於那次實測的一份誠實清單：pandoc 在哪裡會出問題，什麼時候線上轉換工具反而是更好的選擇。
👉 直接看測試結果 | 跳到命令列與線上工具的比較
安裝 Pandoc
Pandoc 是單一執行檔，各主流平台都有安裝程式：
- macOS：
brew install pandoc - Windows：
winget install --id JohnMacFarlane.Pandoc（或使用 MSI 安裝程式） - Debian/Ubuntu：
sudo apt install pandoc
在相信系統內建的舊版本之前有一點要留意：發行版套件庫裡的 pandoc 往往落後好幾年。Ubuntu LTS 長期停在 2.x，而目前的釋出主線是 3.x——下文你會看到，版本新舊直接決定哪些內容能乾淨轉換。用 pandoc --version 查一下自己的版本。
基本轉換指令解析
最精簡的指令已經能用，但在實際專案裡，真正扛事的是這幾個選項：
pandoc report.md -f gfm -o report.docx --toc
| 選項 | 作用 | 什麼時候需要 |
|---|---|---|
-f gfm | 以 GitHub Flavored Markdown 讀取 | 檔案裡用了表格、任務清單或刪除線 |
-o report.docx | 指定輸出檔案，格式由副檔名推斷 | 一律需要 |
--toc | 依標題自動插入目錄 | 超過幾頁的文件 |
--reference-doc | 套用範本 DOCX 裡的字型和樣式 | 公司品牌規範（見下一節） |
為什麼用 -f gfm 而不是 pandoc 預設的 Markdown 方言？因為現在大多數人寫的 Markdown——GitHub README、ChatGPT 和 Claude 的輸出、Notion 匯出——都是 GFM。pandoc 的預設方言比較偏學術：它啟用註腳和引用文獻，但對個別語法的解讀不太一樣。如果你的來源檔出自 AI 助理或開發者工具，gfm 是更穩妥的讀取器。
關於數學公式：在目前版本的 pandoc 裡，GFM 讀取器下 $...$ 和 $$...$$ 直接可用，公式會變成 Word 原生方程式而不是圖片。下文會展開講，因為這是網路上以訛傳訛最嚴重的一條 pandoc 行為。
用 reference-doc 範本客製輸出樣式
pandoc 產生的 DOCX 在 Word 裡打開是一副通用樣式。如果文件必須符合公司範本，靠選項是修不出來的——要用參考文件（reference document）。
整個工作流程分三步：
-
先產生 pandoc 的預設範本當起點：
pandoc -o custom-reference.docx --print-default-data-file reference.docx -
用 Word 打開
custom-reference.docx，編輯其中的樣式——標題 1、內文、表格、程式碼區塊。這個檔案裡的文字內容會被忽略，只有樣式和頁面設定會被沿用。 -
帶上範本執行轉換：
pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
pandoc 手冊記載了哪些樣式名稱會被識別。理解這套機制的關鍵心智模型：你不是在替某一份文件排版，而是把公司的 Word 樣式教給 pandoc 一次，之後每次轉換都能重複使用。
批次轉換多個檔案
這是命令列真正輾壓任何網頁工具的地方。轉換整個資料夾：
Bash（macOS/Linux）：
for f in docs/*.md; do
pandoc "$f" -f gfm -o "${f%.md}.docx"
done
PowerShell（Windows）：
Get-ChildItem docs -Filter *.md | ForEach-Object {
pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}
而且 pandoc 只是單一相依項目，放進 CI 毫不費事。下面這個 GitHub Actions 步驟會在每次 push 時重新產生文件的 Word 副本：
- uses: pandoc/actions/setup@v1
- run: |
for f in docs/*.md; do
pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
done
不少團隊用這個模式替 Markdown 維基維護一份 Word 鏡像，用於法遵審查或交付客戶。同一批檔案只要轉換超過兩次，這段指令稿立刻回本。
Pandoc 的真實限制（3.7 實測）
我跑的測試是這樣的：一個 Markdown 檔案，包含一個表格、一個任務清單、行內公式（$E = mc^2$）、一個多行顯示公式、一個 Mermaid 流程圖和一個 GFM 提示區塊。用 pandoc 3.7.0.2 轉換後，解壓縮 .docx，直接讀 word/document.xml。三個發現。
數學公式轉 Word：比傳聞的好得多
文件 XML 裡有兩個 <m:oMath> 區塊——每條公式一個。這是 OMML，Word 的原生方程式格式。兩條公式在 Word 方程式編輯器裡都完全可編輯，能以印刷品質呈現，複製貼上到其他 Office 文件也不會壞。
這直接推翻了舊教學裡至今還看得到的一種說法（直到不久前，我們自己的一篇指南裡也有）：複雜 LaTeX 會被點陣化成圖片。在目前版本的 pandoc 裡不會。標準 LaTeX 數學——分數、總和、希臘字母、上下標——開箱即用地轉成原生方程式。
誠實的界線在這裡：pandoc 處理的是標準 LaTeX 數學語法，不是任意 LaTeX。自訂的 \newcommand 巨集、TikZ 圖形和依賴套件的環境都過不去。另外如果你的發行版裝的是 pandoc 2.x，行為會不同——先跑 pandoc --version 再怪工具。
Mermaid 才是真正的斷點
Mermaid 流程圖沒有變成圖表。它以逐字的等寬文字輸出——原始的 flowchart LR 原始碼，套著程式碼區塊樣式。文件 XML 裡繪圖物件的數量是零。
這個問題比五年前重要得多，因為 AI 助理偏愛 Mermaid。請 ChatGPT 或 Claude 畫一張架構總覽，回覆裡多半帶一個 mermaid 程式碼區塊。用 pandoc 轉換這段對話，Word 文件裡出現的就是一段看起來像沒刪乾淨的原始碼。如果這正是你的工作流程，我們關於把 ChatGPT 輸出匯出成 Word 的教學涵蓋了 AI 場景的細節。
命令列下有解法：mermaid-filter，一個在轉換過程中算繪圖表的 pandoc 過濾器。它確實能用，但要誠實掂量安裝成本——它是一個 npm 套件，會透過 Puppeteer 拉下來一個無頭 Chromium，pandoc 的呼叫也變成 pandoc -F mermaid-filter ...。對每天都要轉換圖表的文件管線，這筆設定成本攤下來划算；對今天下午就要交的一份報告，它是繞路。
邊緣處的小幅保真損失
同一次測試還有兩個比較不顯眼的發現。GFM 提示區塊（> [!NOTE]）文字保留，但彩色標註樣式不見了——在 Word 裡它們就是普通引用區塊。任務清單項目則變成普通清單文字，而不是 Word 的核取方塊控制項。兩者都不會毀掉文件，但都抹平了作者多半是刻意選擇的格式。如果你的轉換還出了別的狀況，我們在常見 Markdown 轉換問題裡整理了高頻失效模式。
命令列還是線上轉換工具？
測完之後，我真正會採用的決策框架是這張表：
| 你的情況 | 更合適的工具 | 原因 |
|---|---|---|
| 要轉很多檔案，或反覆轉同一批檔案 | Pandoc | 指令稿加 CI 讓重複轉換零成本 |
| 需要自動套用公司 Word 樣式 | Pandoc | --reference-doc 在這方面無可取代 |
| 離線或隔離網路環境 | Pandoc | 單一執行檔，不用連網 |
| 只有一份文件，馬上要交 | 線上轉換工具 | 零安裝，不用管版本 |
| 文件裡有 Mermaid 圖表 | 線上轉換工具 | 圖表直接算繪成圖表，不需過濾器鏈 |
| 公司電腦鎖權限，裝不了軟體 | 線上轉換工具 | 瀏覽器裡就能跑 |
| 大量 LaTeX 公式 | 兩者皆可 | 現代 pandoc 對標準公式處理得很好，我們也是 |
兩條路都是正路。任何週期性執行的管線裡，pandoc 都配得上一席之地。而「五分鐘內我就要一份 .docx」的一次性場景——尤其牽涉 Mermaid 時——用免費的線上 Markdown 轉 Word 轉換器能直接拿到一份公式和圖表都完好呈現的乾淨文件，什麼都不用裝。
常見問題
問：可以不安裝任何軟體就把 Markdown 轉成 Word 嗎？
答：命令列做不到——pandoc 必須安裝。如果安裝軟體不可行，瀏覽器端轉換器是務實的選擇：轉換在伺服器端完成，你直接下載成品 .docx。
問：pandoc 會把 LaTeX 公式轉成真正的 Word 方程式嗎？
答：會。在我們用 pandoc 3.7.0.2 做的測試裡，行內和顯示公式都變成了原生 OMML 方程式，可在 Word 方程式編輯器中編輯。例外是非常舊的 pandoc 版本和自訂 LaTeX 巨集。
問：為什麼我的 Mermaid 圖表在 Word 裡顯示成程式碼？
答：pandoc 把 mermaid 程式碼區塊當作字面程式碼處理，不會算繪圖表。要嘛給管線加上 mermaid-filter（需要 Node.js），要嘛換一個內建 Mermaid 算繪的轉換器。
問：怎樣保留公司的字型和標題樣式？
答：用 --reference-doc=template.docx。在 Word 裡把範本的樣式改好一次，pandoc 每次轉換都會套用。範本裡的內容會被忽略，只有樣式會被沿用。
問：-f markdown 和 -f gfm 有什麼差別？
答：markdown 是 pandoc 自家的擴充方言（註腳、引用文獻）；gfm 對應 GitHub、ChatGPT 和多數現代工具的輸出——表格、任務清單、刪除線。轉換 AI 產生或開發者寫的 Markdown 時，gfm 的意外更少。
問：pandoc 能把 Word 轉回 Markdown 嗎？
答：能——把參數反過來：pandoc report.docx -o report.md。往返轉換會遺失部分 Word 專屬格式（文字方塊、註解），所以把它當內容搬遷用，別指望無損循環。
相關資源
- Markdown 轉 Word 完整指南：命令列之外的完整轉換方案全景
- ChatGPT 轉 Word：AI 產生文件的 Markdown 工作流程
- Markdown 轉 PDF：交付物是 PDF 時看這篇
- 常見 Markdown 轉換問題：表格錯亂、編碼異常與格式漂移的修法
結論
「在命令列把 Markdown 轉成 Word」的正確答案依然是 pandoc——單一檔案一條指令，整個資料夾一段指令稿，公司樣式交給 --reference-doc。我們的測試顯示它的公式支援好過口碑：標準 LaTeX 會變成真正可編輯的 Word 方程式。
它真正的短板在視覺層：Mermaid 圖表會以原始碼的形式落進文件，除非你額外掛上一條基於 Node 的過濾器鏈。所以按工作流程選工具。純文字文件的週期性管線：用 pandoc 寫成指令稿。帶圖表又趕時間的單份文件：在瀏覽器裡轉換，公式和流程圖都完好保留。
參考資料
- Pandoc User's Guide — 官方手冊：讀取器、輸出器、
--reference-doc與公式處理 - Installing pandoc — 各平台官方安裝程式
- mermaid-filter — 算繪 Mermaid 圖表的社群 pandoc 過濾器
- pandoc/actions — 在 CI 中使用 pandoc 的官方 GitHub Actions
覺得好用？分享給更多朋友吧！
