摘要：Markdown 转 HTML 简单，但目录渲染出来却点不动——根因是标题缺 id 锚点。本文讲清修复思路（
toc扩展 +md.toc），并介绍成品脚本的功能亮点与用途，完整示例代码关注公众号获取。
一、背景：从"一把梭"到踩了一个坑
之前 《html显示Markdown语法文本的几种方案》 介绍过使用Python 的markdown库读文件、转语法、套样式模板，一条命令把.md语法字符串变成静态.html文件。
处理简单文档（标题、表格、代码块）时一切正常；但把文档升级成长篇、带目录之后，问题来了：
转换出的 HTML 里，目录渲染出来了，但点击目录项无法跳转，页面纹丝不动。
二、根因：标题缺 id 锚点
默认用法生成的文章里，标题标签<h1>~<h6>没有id属性。而目录要"可跳转"，本质是目录链接href="#xxx"需要命中一个id="xxx"的锚点——没有锚点，链接就落空，点了自然没反应。
这正是"目录点不动"的根源。
三、解决方案：toc扩展
markdown库自带toc扩展，一次性解决两件事：
- 为每个标题自动生成 id 锚点
- 自动生成目录 HTML，可从实例的
toc属性取出、直接插入页面
核心改动就两处：扩展列表里加'toc'，再改用Markdown实例（而非快捷函数）拿目录。这里有个方向性的坑值得记一下：
| 用法 | 能否取到目录 |
|---|---|
markdown.markdown(content, extensions=...)快捷函数 | ❌ 内部新建实例用完即丢，toc取不出来 |
md = markdown.Markdown(extensions=...)→md.convert(content)→md.toc | ✅ 保留下实例，目录随便取 |
一句话：要目录，就别用快捷函数。
四、成品脚本的功能亮点 & 用途
修复的同时，这个脚本把"成品网页"也武装齐了：
1. 一键生成，纯本地离线python md_to_html.py，传输入输出路径即可。不联网、不上传、不改 Markdown 源文件，内网照用，隐私友好。
2. 自动带目录（TOC）且可点击跳转
长文档的救命功能：目录自动生成、自动锚定，读者点一下就能跳到对应章节。
3. 内置基础样式，开箱即看
自带一份 CSS：中文字体排版、标题层级配色、圆角代码块、带边框表格、引用样式、图片自适应。转出来是"精装房"，不是大白板。
4. 支持表格 / 代码块等常用语法tables、fenced_code扩展覆盖技术文档主力语法，表格、围栏代码块在网页里正常呈现。
5. 函数化，可批量复用
封装成md_to_html(md_file, html_file)，可循环处理多个文件，接进文档发布流水线，或做本地知识库展示。
五、效果
- 转换出的页面顶部是可点击目录，点击即跳到对应标题
- 标题有层级配色、正文行距舒适、表格带边框、代码块圆角有底色
- 命令行输出
HTML 已生成: output.html，双击即可预览
六、小结
| 项 | 说明 |
|---|---|
| 问题 | 标题缺 id 锚点，目录无法跳转 |
| 修复 | 加toc扩展，用Markdown实例 +md.toc |
| 配套 | 内置 CSS、表格/代码块支持、可批量 |
| 产出 | 带目录、可跳转、有样式的静态 HTML |
📮 获取完整示例代码
上文只讲了思路与亮点。修复前 / 修复后两版完整可运行代码、可直接套用的 CSS 模板、以及toc扩展的更多配置项，整理好了放在完整示例文档里。
📩点击阅读原文获取完整示例代码文档。
#Python #Markdown #HTML #TOC #静态网页 #文档生成
