Pandoc Word 到 Markdown：命令列轉換指南

Pandoc 是目前最強大的文件轉換工具。它可以在數十種格式之間進行轉換，包括 .docx 到 Markdown，併為您提供對輸出的細粒度控制。本指南涵蓋了您需要使用的所有內容 Pandoc 用於 Word 到 Markdown 轉換。

Pandoc 是什麼？

Pandoc 是一個免費的開源命令列工具，可在格式之間轉換文件。它支援 40 多種輸入和輸出格式。對於 Word 到 Markdown 的轉換，Pandoc 是黃金標準——比任何基於瀏覽器的工具都更可配置，包括 WordToMD.

何時使用 Pandoc 與 WordToMD：

安裝 Pandoc

Windows

從以下位置下載安裝程式 pandoc.org/installing.html，或使用包管理器：

# Winget
winget install pandoc

# Chocolatey
choco install pandoc

# Scoop
scoop install pandoc

macOS

# Homebrew
brew install pandoc

# MacPorts
sudo port install pandoc

Linux

# Ubuntu/Debian
sudo apt-get install pandoc

# Fedora
sudo dnf install pandoc

# Arch
sudo pacman -S pandoc

驗證安裝：

pandoc --version

基本轉換命令

pandoc document.docx -o output.md

就是這樣。Pandoc 推斷輸入格式 .docx 和輸出格式 .md.

更明確的版本：

pandoc -f docx -t markdown document.docx -o output.md

輸出格式選項

Pandoc 提供了多種 Markdown 變體作為輸出：

# GitHub Flavored Markdown (GFM)
pandoc document.docx -t gfm -o output.md

# CommonMark
pandoc document.docx -t commonmark -o output.md

# Pandoc's extended Markdown (most features)
pandoc document.docx -t markdown -o output.md

# Standard Markdown (basic)
pandoc document.docx -t markdown_strict -o output.md

推薦使用 GFM 適用於大多數用例（GitHub、Obsidian、GitBook、Notion）。

有用的轉換選項

提取媒體檔案

.docx 中嵌入的影像被提取到目錄中：

pandoc document.docx --extract-media=./media -o output.md

這會將影像儲存到 ./media/ 並將 Markdown 影像引用新增到輸出中。

換行線

控制輸出中的換行：

# No wrapping (one paragraph = one line)
pandoc document.docx --wrap=none -o output.md

# Wrap at 80 characters
pandoc document.docx --wrap=auto --columns=80 -o output.md

--wrap=none 用於版本控制的 Markdown — 它會生成更清晰的 Git 差異。

目錄

pandoc document.docx --toc -o output.md

帶有後設資料的獨立文件

pandoc document.docx -s -o output.md

的 -s （獨立）標誌從文件的後設資料生成 YAML frontmatter。

批次轉換

轉換目錄中的所有 .docx 檔案：

Windows PowerShell

Get-ChildItem -Filter "*.docx" | ForEach-Object {
    $output = [System.IO.Path]::ChangeExtension($_.Name, ".md")
    pandoc $_.FullName -t gfm --wrap=none -o $output
    Write-Host "Converted: $($_.Name) → $output"
}

Bash (macOS/Linux)

for file in *.docx; do
    output="${file%.docx}.md"
    pandoc "$file" -t gfm --wrap=none -o "$output"
    echo "Converted: $file → $output"
done

有關更多批次轉換選項，請參閱 批次將 Word 轉換為 Markdown.

使用 Lua 過濾器自定義輸出

Pandoc 支援在轉換期間轉換文件 AST 的 Lua 過濾器：

pandoc document.docx --lua-filter=my-filter.lua -o output.md

新增自定義 frontmatter 塊的 Lua 過濾器示例：

-- add-frontmatter.lua
function Meta(meta)
  meta.draft = false
  meta.author = "WordToMD Team"
  return meta
end

這是瀏覽器工具無法比擬的定製。

比較 Pandoc 和 mammoth.js 輸出

WordToMD 在底層使用 mammoth.js。Pandoc 使用自己的解析器。主要區別：

對於複雜的文件，Pandoc 提供更完整的輸出。對於簡單文件，WordToMD 零設定速度更快。

Pandoc 預設檔案

對於使用相同設定的重複轉換，建立一個預設檔案：

# my-defaults.yaml
from: docx
to: gfm
wrap: none
extract-media: ./media
standalone: true

然後執行：

pandoc document.docx -d my-defaults.yaml -o output.md

在 CI/CD 中使用 Pandoc

對於自動化管道（GitHub Actions 等）：

# .github/workflows/convert-docs.yml
- name: Install Pandoc
  run: sudo apt-get install pandoc

- name: Convert Word docs to Markdown
  run: |
    for f in docs/*.docx; do
      pandoc "$f" -t gfm --wrap=none -o "${f%.docx}.md"
    done

FAQ

Pandoc 輸出 \ 行延續。我該如何刪除它們？ 新增 --wrap=none 停用硬換行。

我的表在 Pandoc 輸出中看起來亂碼。 嘗試 -t gfm 用於 GFM 表語法，而不是預設的 Pandoc Markdown 表。

影像未顯示在輸出中。 新增 --extract-media=./images 提取嵌入影像。然後在您的目標環境中正確引用它們。

Pandoc 將智慧引號轉換為 " 字元 — 如何保留它們？ 新增 --no-highlight 或修改模板。特別是對於智慧引號，它們應該在大多數輸出​​格式中預設保留。

Pandoc 和 WordToMD 如何比較 DOCX 與 Markdown？ 兩者都適用於標準文件。WordToMD 需要零設定併產生乾淨的 GFM 輸出。Pandoc 需要安裝，但可以更完整地處理複雜文件（影像、數學、註釋、腳註）。

結論

Pandoc 是最強大的工具 Word 轉 Markdown 轉換，特別是批處理、自定義輸出格式和 CI/CD 管道。無需安裝即可快速、一次性轉換， WordToMD 立即完成工作。這兩個工具相輔相成。