用 markdown 库最直接，不依赖系统环境，纯 Python 实现，但默认不渲染表格、代码高亮等扩展功能；需显式传入 extensions=['tables', 'fenced_code'] 启用表格和代码块，加 'codehilite' 并安装 pygments 实现语法高亮，中文锚点失效可配 toc 扩展与自定义 slugify 函数。
用 markdown 库最直接，不依赖系统环境，纯 Python 实现，但需注意默认不渲染表格、代码高亮等扩展功能。
为什么不用 pandoc 命令行？
虽然 pandoc 功能强、输出质量高，但要求系统预装且路径可访问，跨平台部署时容易卡在 FileNotFoundError: [Errno 2] No such file or directory: 'pandoc'。如果只是做基础转换（标题、列表、段落），markdown 库更轻量、更可控。
- 确认已安装：
pip install markdown - 它默认只启用标准 CommonMark 子集，不支持
tables、fenced_code等扩展，需显式开启 - 不处理图片路径重写、CSS 注入、模板套用——这些得自己补逻辑
如何启用表格和代码块渲染？
Markdown 原生语法如 | A | B | 和 ```python 在默认 markdown.markdown() 下会被忽略为纯文本。必须传入 extensions 参数：
import markdown html = markdown.markdown(md_text, extensions=['tables', 'fenced_code'])
-
tables：解析竖线表格（需确保 Markdown 表格语法规范，首行末尾不能多空格） -
fenced_code：识别```lang块，但仅生成<pre><code>，不带语法高亮 - 若要高亮，加
codehilite扩展：extensions=['fenced_code', 'codehilite']，并确保安装pygments
批量转换时怎么保留原始文件结构？
别用 os.listdir() 简单遍历——它不递归，也不过滤非 .md 文件。推荐 pathlib + glob：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“Python免费学习笔记（深入）”；
from pathlib import Path
md_files = list(Path("docs").rglob("*.md")) # 递归找所有 .md
for md_path in md_files:
html_path = md_path.with_suffix(".html")
with open(md_path, encoding="utf-8") as f:
html = markdown.markdown(f.read(), extensions=["tables", "fenced_code"])
with open(html_path, "w", encoding="utf-8") as f:
f.write(f"<!DOCTYPE html>\n<html><body>{html}</body></html>")-
rglob自动处理子目录，比os.walk更简洁 -
with_suffix(".html")安全替换后缀，不会误改README.md.bak这类文件 - 注意编码：Windows 上常见
UnicodeDecodeError，强制用encoding="utf-8"
中文标题锚点失效怎么办？
默认 markdown 生成的 <h2 id="xxx"> 中文 ID 会变成 id="%E4%B8%AD%E6%96%87"，浏览器能跳转，但部分静态站点生成器或 TOC 插件不认 URL 编码 ID。解决方法是加 toc 扩展并配置：
markdown.markdown(md_text, extensions=[
'tables', 'fenced_code',
'toc' # 启用目录生成
], extension_configs={
"toc": {"slugify": lambda x, **y: x.replace(" ", "-")} # 简单去空格，不编码中文
})-
toc扩展自带slugify函数，默认用markdown.extensions.toc.make_anchor_id，会编码中文 - 自定义
slugify是最简方案；若需真正语义化 ID（如 “安装步骤” → “an-zhuang-bu-zhou”），得引入python-slugify - 这个配置只影响
<h>标签的id，不影响正文内容
真正麻烦的是 CSS 样式和资源路径——HTML 里相对路径如  在转换后仍指向原位置，但 HTML 可能放在不同目录。这部分没银弹，得按实际部署结构手动调整 base_url 或用正则替换路径。
