Python批量Markdown转HTML：两种方案与目录遍历

脚本专家

在技术写作和项目文档中，Markdown 因语法简洁而被广泛使用，但浏览器本身不能直接渲染 .md 文件。把 Markdown 发布到网页或接入内容管理系统之前，通常要转成 HTML。Python 里常见的做法有两类：一类是用 markdown 这类纯解析器直接处理标记文本；另一类是先借助文档模型类库把 Markdown 加载成结构化文档对象，再导出 HTML。本文围绕 Spire.Doc for Python 和 markdown 库，整理单文件转换、目录批量转换、保留目录结构、并行处理等可落地代码，并说明各自的参数含义和已知边界。

一、环境与工具定位

Spire.Doc for Python 是文档处理库，运行时不依赖本地安装 Microsoft Word 或其他办公套件。它把 Markdown 文件加载到 Document 对象，再通过内置格式映射输出 HTML。纯解析器方案则以 markdown 库为主，直接对文本做语法解析并输出 HTML 标签。安装命令如下：

2. pip install Spire.Doc
3. pip install markdown

复制代码

二、单文件转换：加载与保存

单文件转换的核心只有三步：创建文档对象、加载 Markdown、保存为 HTML。

2. from spire.doc import *
4. doc = Document()
5. doc.LoadFromFile('example.md', FileFormat.Markdown)
6. doc.SaveToFile('example.html', FileFormat.Html)
7. doc.Close()

复制代码

LoadFromFile 的第二个参数 FileFormat.Markdown 指定源文件的解析格式；SaveToFile 的 FileFormat.Html 声明输出目标；doc.Close() 用于释放文档对象占用的资源，在循环处理多个文件时尤其需要保留，否则可能出现内存累积或文件句柄未释放的问题。

执行后生成的 HTML 文件会保留 Markdown 中标题、列表、链接、代码块等基础元素的语义结构。需要明确的是，转换产物是结构化的 HTML，而非带样式的页面。Markdown 本身不携带 CSS 信息，输出的 HTML 在浏览器中呈现为默认样式；若需要特定排版效果，仍需自行附加样式表。

三、目录遍历批量转换

实际工作中更常见的情形是一个目录下存在多个待转换的 .md 文件。结合 os 模块遍历目录，对每个文件执行独立的转换流程即可。

2. import os
3. from spire.doc import *
5. input_folder = 'markdown_files'
6. output_folder = 'html_files'
7. os.makedirs(output_folder, exist_ok=True)
9. for filename in os.listdir(input_folder):
10.     if filename.endswith('.md'):
11.         doc = Document()
12.         doc.LoadFromFile(os.path.join(input_folder, filename), FileFormat.Markdown)
13.         output_path = os.path.join(output_folder, filename.replace('.md', '.html'))
14.         doc.SaveToFile(output_path, FileFormat.Html)
15.         doc.Close()

复制代码

这段代码中有两个细节值得注意。第一，每次循环都新建一个 Document 对象，而非复用同一实例。文档模型类库在多次加载之间可能存在状态残留，新建对象可避免内容叠加或格式串扰。第二，os.makedirs 的 exist_ok=True 参数确保输出目录不存在时自动创建，存在时也不报错。endswith 过滤则保证混合目录中只有 .md 文件被处理。

四、转换效果与已知边界

从一般性的使用反馈来看，这条路径对常见 Markdown 语法元素，包括标题层级、有序与无序列表、粗体与斜体、行内代码与代码块、超链接、图片引用，能够生成对应的 HTML 标签。但有几个边界需要如实说明。

样式与 CSS 的缺失是首要限制。Markdown 源文件不携带样式信息，生成的 HTML 仅包含语义标签。如果发布平台要求内联样式或特定的 class 命名，需要在转换后另行处理。免费版的段落上限在长文档场景下是硬约束：500 个段落的限制对于常规博客文章通常足够，但对于书籍章节或大型技术规范则可能触发截断。此外，该库的 Markdown 解析器对非标准扩展语法的支持程度，取决于具体版本的内置实现，非常规 Markdown 方言的转换结果需要以实际输出为准，不宜预设完全兼容。

五、纯解析器方案：最小可运行版本

用 markdown 库处理批量转换，核心步骤同样是遍历目录、逐个解析、写入对应的 .html 文件。最简版本如下：

2. from pathlib import Path
3. import markdown
5. src_dir = Path('docs_md')
6. out_dir = Path('docs_html')
7. out_dir.mkdir(exist_ok=True)
9. for md_file in src_dir.glob('*.md'):
10.     md_text = md_file.read_text(encoding='utf-8')
11.     html_body = markdown.markdown(md_text)
12.     (out_dir / f'{md_file.stem}.html').write_text(html_body, encoding='utf-8')

复制代码

这个版本能跑通，但会丢掉表格、代码块和中文标题锚点，因为 markdown.markdown() 默认只启用基础语法。

六、启用扩展、完整 HTML 骨架与代码高亮

要保留表格、围栏代码块和代码高亮，需要显式传入 extensions，并可用 extension_configs 控制高亮行为。

2. from pathlib import Path
3. import markdown
5. SRC = Path('docs_md')
6. OUT = Path('docs_html')
8. TEMPLATE = """<!DOCTYPE html>
9. <html lang='zh-CN'>
10. <head>
11. <meta charset='UTF-8'>
12. <title>{title}</title>
13. <style>
14. body {{ max-width: 860px; margin: 2rem auto; padding: 0 1rem;
15. font-family: system-ui, sans-serif; line-height: 1.7; }}
16. pre {{ background: #f5f5f5; padding: 1rem; overflow-x: auto; }}
17. table {{ border-collapse: collapse; width: 100%; }}
18. th, td {{ border: 1px solid #ddd; padding: 6px 10px; }}
19. </style>
20. </head>
21. <body>{body}</body>
22. </html>"""
24. def convert_one(md_path: Path) -> None:
25.     md_text = md_path.read_text(encoding='utf-8')
26.     html_body = markdown.markdown(
27.         md_text,
28.         extensions=['tables', 'fenced_code', 'codehilite', 'toc', 'sane_lists'],
29.         extension_configs={
30.             'codehilite': {'guess_lang': False, 'css_class': 'codehilite'}
31.         },
32.     )
33.     html = TEMPLATE.format(title=md_path.stem, body=html_body)
34.     (OUT / f'{md_path.stem}.html').write_text(html, encoding='utf-8')
36. OUT.mkdir(exist_ok=True)
37. for f in SRC.rglob('*.md'):
38.     convert_one(f)

复制代码

这里 extensions 中的 tables、fenced_code、codehilite、toc、sane_lists 分别对应表格、围栏代码块、代码高亮、目录锚点和列表解析；extension_configs 中 guess_lang=False 避免误判语言，css_class 指定高亮 CSS 类。TEMPLATE 只是外层 HTML 骨架，样式仍需要按发布平台要求补充。

七、保留子目录结构

rglob('*.md') 会递归处理子目录，但上面的输出全部平铺到 OUT 下。如果不同子目录里有同名文件，后面的会覆盖前面的。用 relative_to 加上 with_suffix 可以保留目录映射。

2. from pathlib import Path
3. import markdown
5. SRC = Path('docs_md')
6. OUT = Path('docs_html')
8. def convert_tree(src: Path, out: Path):
9.     for md_file in src.rglob('*.md'):
10.         rel = md_file.relative_to(src)
11.         target = (out / rel).with_suffix('.html')
12.         target.parent.mkdir(parents=True, exist_ok=True)
13.         md_text = md_file.read_text(encoding='utf-8')
14.         html_body = markdown.markdown(
15.             md_text,
16.             extensions=['tables', 'fenced_code', 'toc', 'sane_lists'],
17.         )
18.         full = f"<!DOCTYPE html><html><head><meta charset='UTF-8'>" \
19.                f"<title>{md_file.stem}</title></head><body>{html_body}</body></html>"
20.         target.write_text(full, encoding='utf-8')
21.         print(f'✓ {md_file} -> {target}')
23. convert_tree(SRC, OUT)

复制代码

md_file.relative_to(src) 加上 .with_suffix('.html')，是保留目录映射的关键。parents=True 和 exist_ok=True 保证子目录会被自动创建。

八、并行处理：文件多时用得上

单文件转换是 CPU 密集型任务，文件数量上百时串行会明显变慢。可以用 ProcessPoolExecutor 并行处理。

2. from concurrent.futures import ProcessPoolExecutor
3. from pathlib import Path
4. import markdown
6. SRC, OUT = Path('docs_md'), Path('docs_html')
8. def convert(md_file: Path):
9.     rel = md_file.relative_to(SRC).with_suffix('.html')
10.     target = OUT / rel
11.     target.parent.mkdir(parents=True, exist_ok=True)
12.     md_text = md_file.read_text(encoding='utf-8')
13.     html = markdown.markdown(md_text, extensions=['tables', 'fenced_code', 'toc'])
14.     target.write_text(html, encoding='utf-8')
15.     return str(target)
17. if __name__ == '__main__':
18.     files = list(SRC.rglob('*.md'))
19.     with ProcessPoolExecutor() as pool:
20.         for result in pool.map(convert, files):
21.             print('done:', result)

复制代码

if __name__ == '__main__' 在多进程中是必需的，否则 Windows 上会因重复导入而报错。文件数量少于 50 个时，进程池的启动开销可能抵消收益，串行反而更简单。

九、两类方案的选型对比

Python 生态中的 markdown 库直接对文本做语法解析并输出 HTML 标签，不构建文档对象模型。两者差异主要体现在调用方式与输出控制粒度上。纯解析器通常提供扩展参数来控制表格、代码块等特性的解析行为，输出结果易于进一步用字符串处理或模板注入样式；文档模型类库则将加载与导出封装为对象方法，与处理 Word、PDF 等其他格式时的调用逻辑一致，适合已经在使用同一套文档处理流程的场景。

如果项目对 Markdown 扩展语法有较多依赖，或需要精确控制 HTML 的每一个输出细节，纯解析器方案在灵活性和可定制性上通常更直接。文档模型方案的可取之处在于：当同一套代码还需要处理其他文档格式的转换时，可以减少引入不同库的维护成本。

选解析库时还可以参考以下差异：markdown 库扩展生态丰富，支持 tables、fenced_code、toc、codehilite、footnotes，适合大多数场景，稳定且文档全；mistune 内置常用语法，速度最快，适合追求性能、需要处理大量文件的场景；pymarkdown 严格遵循 CommonMark，适合需要规范兼容性、少用扩展的场景。

十、总结

无论是文档模型类库还是纯解析器，Python 把 Markdown 批量转换成 HTML 的核心步骤都只有三步：遍历目录、逐个解析、写入对应的 .html 文件。真正的差异在解析库的选择、扩展的启用、以及输出文件名的映射规则上。采用 Spire.Doc 这类文档模型方案时，需要确认待处理文档的段落规模是否在免费版限制之内，以及输出 HTML 是否需要后续的样式补充；采用 markdown 库时，则要关注扩展是否覆盖实际语法、递归目录是否保留、同名文件是否覆盖、多进程入口保护是否到位。选型时建议根据实际文档规模、语法复杂度和后续样式处理需求进行对比测试。

热心网友5

整理得挺清楚的，两种方案的定位和边界都讲到了，尤其是免费版 500 段落限制、默认 markdown 扩展会丢表格和围栏代码块这两个坑，对实际落地很有提醒价值。 不过正文到完整 HTML 骨架那里好像截断了，后面代码高亮和模板拼接部分没贴完，方便的话可以补全一下，这块对批量生成可直接浏览的页面挺关键。 另外顺着首帖内容补几个落地时容易忽略的点：目录批量转换如果要保留结构，最好用相对路径配合创建父目录，不要只平铺到输出目录；并行处理时每个文件仍要独立创建文档对象并限制并发数，避免文件句柄和内存压力；markdown 方案里扩展建议显式列出来，中文标题锚点也要单独配置，不然生成的目录跳转可能不理想；模板拼接时标题和正文转义、大括号转义都要留意。整体思路很实用，期待后续完整版。

热心网友5

感谢整理，两种方案的定位和取舍讲得很清楚。Spire.Doc 这条路径适合想直接加载文档再导出 HTML 的场景，单文件三步和目录遍历里每次新建 Document、及时 Close 的提醒很实用，能避免批量处理时的资源累积问题。markdown 库方案更轻量，但默认只支持基础语法这一点容易踩坑，后面显式启用扩展、加完整 HTML 骨架和代码高亮的思路是对的。实际使用时我也会特别注意 UTF-8 读写、免费版段落上限以及输出 HTML 不带 CSS 需要后处理这几个边界。整体内容很落地，期待把模板部分补完整。

热心网友5

感谢整理，思路很清晰。单文件转换三步和目录遍历的示例都比较直观，尤其提醒循环里每次新建 Document 并 Close 释放资源，这点很实用。两种方案的定位也讲得明白：Spire.Doc 更像文档模型转换，markdown 库更轻量但需要显式启用扩展。第六部分模板好像没贴完，代码高亮和完整 HTML 骨架那段断在 style 里了，如果能补全会更方便直接照着用。另外批量场景下保留目录结构、并行处理和单个文件失败不影响整批的异常处理，如果后续展开会很有帮助。整体对我这种需要批量转文档的人挺有参考价值。