markdown.markdown()仅输出无结构的HTML片段，缺乏完整文档框架、样式、目录、锚点ID及资源路径处理，需启用extra/codehilite/toc扩展并手动补全HTML模板才能生成可用文档。
直接用 markdown 库就能跑通基础流程，不需要自己解析语法或写渲染器。但想生成可用的文档（带样式、目录、链接跳转），光靠 markdown.markdown() 远远不够——它只输出裸 HTML 片段，没 结构、没 CSS、不处理图片路径、也不生成目录。
为什么不能只调用 markdown.markdown()
这个函数只是把 Markdown 字符串转成一段 HTML 内容（比如 <p>Hello</p>
<ul><li>item</li></ul>），不包含 、、DOCTYPE，也没办法自动加 Bootstrap 样式或锚点 ID。常见错误是直接保存结果到 .html 文件，打开后文字堆在一起、无缩进、标题不可点击、图片 404。
- 输出不含完整 HTML 文档结构 → 浏览器渲染异常或样式丢失
- 标题没有
id属性 → 无法用[TOC]或 JS 生成目录 - 相对路径的图片/链接仍保持原样 → 本地预览时资源加载失败
- 不支持表格、脚注、代码行号等扩展 → 遇到
~~~python块可能被忽略
必须启用的三个扩展：extra、codehilite、toc
它们不是可选插件，而是解决实际问题的刚需配置。缺一不可：
-
extra：支持表格、围栏代码块（```）、定义列表、脚注等常用语法 -
codehilite：给```python这类代码块加上 Pygments 高亮（需提前pip install pygments） -
toc：为每个标题自动添加id，并支持在文档里用[TOC]占位符生成目录
实操写法：
立即学习“Python免费学习笔记（深入）”；
import markdown
md = markdown.Markdown(
extensions=['extra', 'codehilite', 'toc'],
extension_configs={
'codehilite': {'guess_lang': False, 'css_class': 'highlight'},
'toc': {'permalink': True}
}
)
html_body = md.convert(md_text)
toc_html = md.toc # 注意：必须在 convert() 之后取
如何拼出一个能直接打开的完整 HTML 文件
需要手动补全 HTML 模板，并注入内容。关键点在于：路径要相对当前生成位置处理，CSS 要内联或指定 CDN，否则离线打不开。
- 不要硬编码绝对路径；用
os.path.relpath()或直接内联样式避免依赖外部文件 - 如果用 CDN 引入 Bootstrap，确保网络通畅；离线场景建议用
pygments生成的 CSS 内联（PygmentsCssFormatter().get_style_defs()） - 图片路径默认不会重写 → 若源 Markdown 中是
，且目标 HTML 和图片不在同级目录，需手动替换src值 - 生成的
md.toc是带<div class="toc"> 的 HTML 字符串，需插入到模板中合适位置（通常在正文前）<p>最小可用模板示例：</p><pre class='brush:python;toolbar:false;'>template = """<!DOCTYPE html><html><head><meta charset="utf-8"><title>{title}</title><style>{pygments_css}</style></head><body>{toc}<article>{content}</article></body></html> """ html_full = template.format( title="My Doc", pygments_css=formatter.get_style_defs(), toc=toc_html, content=html_body ) </pre><h3>容易被忽略的路径与编码细节</h3> <p>90% 的“生成后图片不显示”“中文乱码”问题都出在这儿：</p> <ul> <li>读取 Markdown 文件时没指定 <code>encoding='utf-8'→ 中文标题变你好 - 用
open(..., 'w')写 HTML 时没加encoding='utf-8'→ 浏览器识别成 GBK，中文全乱码 - Markdown 里写
，但生成 HTML 放在docs/index.html，路径就变成docs/./assets/chart.png→ 必须统一按输出目录为基准重写所有src和href - Windows 下路径分隔符是
，但 HTML 只认/→ 用path.replace('\', '/')统一处理
这些不是“高级技巧”，是每次生成前必须检查的落地细节。漏掉任意一项，文档看起来就是半成品。
