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 立即完成工作。这两个工具相辅相成。