Pandoc是Markdown转Word/PDF的事实标准，Python应仅负责批量调用它；手写渲染逻辑易出错且难控样式，因Markdown不定义排版，而python-docx、weasyprint等无法可靠处理嵌套列表、公式、Mermaid图表等复杂元素。
直接用 pandoc 命令行最稳，Python 脚本只负责批量调用它——自己写解析器或用 python-docx / weasyprint 从头渲染 Markdown，容易翻车且样式难控。
为什么别手写 Markdown → Word/PDF 的 Python 渲染逻辑
Markdown 本身不定义排版，而 Word 和 PDF 都依赖样式树和布局引擎。python-docx 只能插入段落、表格、图片，但无法自动处理嵌套列表、数学公式、自定义标题层级缩进；weasyprint 对 CSS 支持有限，遇到 $$...$$ 或 Mermaid 图表基本挂掉。真实项目里，90% 的格式错乱都源于试图“绕过 pandoc”。
正确做法是让 Python 做它擅长的事：遍历文件、拼接命令、检查返回码、归档输出。
-
pandoc是事实标准，支持 70+ 输入/输出格式，原生理解 YAML front matter、引用、脚注 - 所有主流样式定制（页眉页脚、字体、目录）靠一个
--template或--css参数就能生效 - PDF 输出默认走 LaTeX（质量高），也可切到
weasyprint或wkhtmltopdf后端，无需改 Python 代码
用 subprocess 调用 pandoc 批量转换的最小可行脚本
不要用 os.system——捕获不到错误码，也难做并发控制。核心就三步：找文件、构命令、执行并记录。
News To Markdown
下载
输入文章 URL，返回干净 Markdown。支持17个平台（头条、微信公众号、知乎、36kr、虎嗅、华尔街见闻、澎湃、InfoQ 等）专项优化，双引擎提取、图片本地化、三层抓取策略。常与 browser‑web‑search skill配合：先用 bws 搜索获取 url 列表，再逐篇调用本 skill 提取正文。
立即学习“Python免费学习笔记（深入）”；
示例脚本片段（转 Word）：
import subprocess
import pathlib
<p>md_files = pathlib.Path("docs").rglob("*.md")
for md in md_files:
docx = md.with_suffix(".docx")
cmd = [
"pandoc",
str(md),
"-o", str(docx),
"--standalone",
"--toc",
"--toc-depth=3",
"--reference-doc=template.docx" # 指向你准备好的样式模板
]
result = subprocess.run(cmd, capture_output=True, text=True)
if result.returncode != 0:
print(f"❌ {md.name} -> {docx.name} 失败: {result.stderr[:200]}")- 务必加
--standalone，否则生成的 Word 缺元数据，双击打开可能报错 -
--reference-doc是关键：没有它，Word 输出就是默认宋体五号字，毫无专业感 - PDF 转换只需把
-o后缀改成.pdf，再加--pdf-engine=xelatex（推荐）或--pdf-engine=weasyprint - 大量文件时加
subprocess.Popen+ 进程池，避免阻塞；但别盲目开 50 个进程——xelatex吃内存，16G 内存建议 ≤8 并发
常见失败原因和对应 fix
不是脚本问题，几乎全是 pandoc 环境或路径惹的祸。
-
FileNotFoundError: [Errno 2] No such file or directory: 'pandoc'：没装 pandoc 或不在PATH。Mac 用brew install pandoc，Windows 下载安装包后手动加到系统环境变量 - 中文乱码（Word 中显示方块）：PDF 用
--pdf-engine=xelatex+--variable mainfont="Noto Serif CJK SC"；Word 则必须用--reference-doc指向含中文字体设置的模板，不能只靠--variable - 公式不渲染：
$$E=mc^2$$需加--mathml（HTML/PDF）或--webtex（需联网），Word 不支持原生 LaTeX 公式，得转成图片——用--filter pandoc-fignos配合插件 - 链接失效或图片路径错乱：确保所有
中的路径是相对于 Markdown 文件所在目录的相对路径，不是相对于 Python 脚本路径
真正卡住人的永远不是“怎么写循环”，而是路径是否相对、模板是否存在、中文字体有没有嵌入、公式后端是否匹配——这些细节 Pandoc 文档里散落在不同章节，但批量转换时每个都会突然冒出来咬你一口。
