Python使用pypandoc转换markdown格式文件

各种大模型已经渐渐进入我们的实际应用当中，大模型的输出往往是markdown格式更加友好，但是日常工作中又需要用到docx，pdf之类的文档格式，因此，把md转换为其它格式显得很有必要。

0. pypandoc安装

查看pypandoc在PyPI的官方介绍，我们可以手动安装好pandoc的基础上安装pypandoc

pip install pypandoc

为了解决问题，我们也可以采取一种更懒的手段：

If you want pandoc included out of the box, you can utilize our pypandoc_binary package, which are identical to the “pypandoc” package, but with pandoc included.

直接包含它的二进制文件，安装命令为：

pip install pypandoc_binary

或

pip install pypandoc-binary

我用的是uv进行包管理，命令为：

uv add pypandoc-binary

pyproject.toml文件记录依赖关系如下：

[project]
name = "pypandoc"
version = "0.1.0"
description = "Markdown format to docx or pdf"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "pypandoc-binary>=1.15",
]

1. markdown转换为word的docx格式

1.1 一个简单的例子

工作中需要把一份根据AI建议编写的文档转换为word格式，源文件大致如下：

使用几行简单的代码，即可做转换：

import pypandoc

def main():
    pypandoc.convert_file("./doc/全栈工程师.md", "docx", outputfile="./doc/全栈工程师.docx")

if __name__ == "__main__":
    main()

效果如下：

虽然不算很好，但基本还是能解决不少问题，后续手工调整就行了。

1.2 图文并茂的md怎么破

上述简单的例子是以文本为主的markdown文档，那么对于图文图文码并茂的文档，不知道效果如何？

例如这样一个文档：

代码还是很简单：

# pip install pypandoc-binary
# uv add pypandoc-binary
import pypandoc
def main():
    pypandoc.convert_file("./files/test.md", "docx", outputfile="./output/test.docx")

if __name__ == "__main__":
    main()

转换效果还是可以的：

2. markdown转换为pdf格式

同样，我们也可以用这个库把md格式文件转换为pdf格式文件，代码如下：

import pypandoc
def main():
    pypandoc.convert_file("./files/test.md", "pdf", outputfile="./output/test.pdf")

if __name__ == "__main__":
    main()

2.1 一个运行时错误及解决办法

执行上述代码，会出现这样一个运行错误：

RuntimeError: Pandoc died with exitcode “47” during conversion: pdflatex not found. Please select a different --pdf-engine or install pdflatex

从提示来看是缺PDF转换引擎了，查看pandoc的说明文档我们更能发现这一点。
安装TeX Live（这个东西很大啊……）或MiKTeX（这个小一点），我们可以解决这个问题，但对中文等Unicode字符的支持并不友好。

2.2 曲线解决问题

事实上，在转换为docx没有问题的情况下，我们完全可以把word文档转换为pdf格式：

uv add docx2pdf

# pip install pypandoc-binary
# uv add pypandoc-binary
import pypandoc
# uv add docx2pdf
import docx2pdf
# uv add pdflatex
def main():
    pypandoc.convert_file("./files/test.md", "docx", outputfile="./output/test.docx")
    docx2pdf.convert("./output/test.docx", "./output/test-docx2pdf.pdf")

if __name__ == "__main__":
    main()

3. md转换为html格式

类似地，可以把markdown文件转换为html5格式的页面文件。

# pip install pypandoc-binary
# uv add pypandoc-binary
import pypandoc
def main():
    pypandoc.convert_file("./files/test.md", "html5", outputfile="./output/test.html")

if __name__ == "__main__":
    main()

4. 小结

pypandoc基于pandoc，让格式转换变得相当方便。

5. 参考内容

• pandoc官网
• pypandoc仓库
• TeX Live