在 Python 中把 Markdown 文本转换成 HTML 网页最经典、最常用的工具是Python-Markdown第三方库。它完全兼容标准 Markdown 语法还可以通过「扩展插件」解锁表格、代码高亮、自动目录、脚注等进阶功能非常适合生成技术文档、博客页面、笔记导出等场景新手几分钟就能上手。本文从环境搭建、基础转换、进阶扩展到完整实战全程配可运行代码 逐行解释零基础也能做出美观的 HTML 文档。一、环境准备1. 安装库markdown是第三方库需要通过 pip 安装打开终端执行pip install markdown2. 验证安装执行下面的代码不报错就说明安装成功import markdown print(markdown.__version__)补充说明它的核心作用输入 Markdown 格式的文本 / 文件输出对应的 HTML 标签字符串原生只支持基础 Markdown 语法进阶功能需要开启对应的「扩展」可以理解为官方插件生成的默认 HTML 只有标签没有样式需要自己加 CSS 才能变成美观的页面二、基础入门两种核心转换方式方式 1字符串转换内存中直接转适合处理短文本、动态生成的 Markdown 内容直接在内存里转换不需要读写文件。完整示例# 1. 导入库 import markdown # 2. 准备一段Markdown格式的文本 md_text # Python 入门教程 这是一篇用Markdown写的教程**加粗强调重点***斜体标注说明*。 ## 一、基础语法 学习Python需要掌握以下内容 - 变量与数据类型 - 条件判断与循环 - 函数与模块 ## 二、学习建议 多写代码多练习参考官方文档 [Python官方网站](https://www.python.org/) 提示坚持每天练习进步会很快。 # 3. 核心方法把Markdown转换成HTML # markdown.markdown(markdown文本) 返回HTML字符串 html_text markdown.markdown(md_text) # 4. 打印转换结果 print(转换后的HTML内容) print(html_text)运行结果简化h1Python 入门教程/h1 p这是一篇用Markdown写的教程strong加粗强调重点/strongem斜体标注说明/em。/p h2一、基础语法/h2 p学习Python需要掌握以下内容/p ul li变量与数据类型/li li条件判断与循环/li li函数与模块/li /ul ...代码解释markdown.markdown()是最核心的转换函数输入 Markdown 字符串输出 HTML 字符串自动对应关系#转h1、**转strong、-转ulli、转blockquote原生支持所有基础 Markdown 语法标题、段落、加粗、斜体、列表、引用、链接、图片、分割线方式 2本地文件转换.md 转 .html这是日常最常用的场景读取本地已经写好的.md文件转换后保存成.html网页文件。完整示例import markdown # 第一步读取本地Markdown文件 # 必须指定 encodingutf-8否则中文会乱码 with open(我的笔记.md, r, encodingutf-8) as f: # 读取文件全部内容得到Markdown字符串 md_content f.read() # 第二步转换为HTML # 这里先演示基础转换后面会讲解扩展参数 html_content markdown.markdown(md_content) # 第三步保存为HTML文件 with open(我的笔记.html, w, encodingutf-8) as f: f.write(html_content) print(转换完成已生成 我的笔记.html)关键说明中文乱码问题读写文件必须加encodingutf-8这是新手 100% 会踩的坑转换后得到的只是 HTML 正文片段没有head、body等完整页面结构浏览器也能打开但样式很简陋后面的实战部分会教你加上样式生成完整美观的网页三、核心进阶扩展插件Extensions原生markdown只支持最基础的 Markdown 语法表格、任务列表、代码高亮、自动目录这些常用功能都需要开启对应的扩展插件才能使用。这是新手最容易踩坑的地方 —— 写了表格语法却不生效大概率是没开扩展。使用方法在markdown.markdown()方法中加extensions参数传入扩展名称的列表即可html markdown.markdown(md_text, extensions[扩展1, 扩展2])最常用的 5 个扩展1.extra全能扩展合集新手必开这是最常用的扩展一次性打包了表格、脚注、定义列表、属性列表等高频功能日常使用开这一个就够了。示例Markdown 表格转换import markdown md_table ### 学生成绩表 | 姓名 | 年龄 | 分数 | |------|------|------| | 小明 | 18 | 95 | | 小红 | 17 | 88 | | 小刚 | 19 | 92 | # ❌ 不开扩展表格会被当成普通文本格式错乱 # html1 markdown.markdown(md_table) # ✅ 开启extra扩展正确转换成标准table表格标签 html2 markdown.markdown(md_table, extensions[extra]) print(html2)开启后会自动生成带table、tr、th、td的标准表格 HTML 代码。2.toc自动生成目录自动根据文章的标题层级生成带锚点的目录只需要在 Markdown 里写[TOC]标记转换时会自动替换成目录。示例import markdown md_text [TOC] # 第一章Python基础 ## 1.1 变量 变量的定义与使用 ## 1.2 数据类型 常见数据类型介绍 # 第二章函数 ## 2.1 函数定义 def关键字的用法 # 开启toc扩展 html markdown.markdown(md_text, extensions[toc]) print(html)效果[TOC]的位置会被替换成嵌套的目录列表点击目录标题可以跳转到对应章节非常适合长文档。3.codehilite代码块语法高亮给代码块加上语法高亮颜色让代码更易读。需要先安装依赖库pygmentspip install pygments示例import markdown md_code 下面是一段Python代码 python def add(a, b): # 计算两数之和 return a b print(add(1, 2))开启 codehilite 扩展linenumsTrue 表示显示行号html markdown.markdown( md_code, extensions[codehilite], extension_configs{ codehilite: {linenums: True} } ) 注意这个扩展只会给代码标签加上 CSS 类名不会自带颜色需要额外引入高亮样式文件后面完整实战会教你加样式。 --- #### 4. nl2br换行自动转换行标签 标准 Markdown 里单回车不会换行必须空一行才会分段。开启 nl2br 后每一个回车都会自动转换成 br 换行标签适合习惯写短行、随手回车的场景。 python html markdown.markdown(md_text, extensions[nl2br])5.sane_lists智能列表优化列表的解析逻辑避免混合有序 / 无序列表时出现格式错乱让解析结果更符合直觉。四、完整实战生成带样式的美观 HTML默认转换出来的 HTML 只有标签没有任何样式打开非常简陋。我们可以给它加上基础 CSS 样式生成一个排版美观、带代码高亮、带目录的完整网页新手可以直接套用这个模板。完整代码import markdown # 1. 读取Markdown文件 with open(我的笔记.md, r, encodingutf-8) as f: md_text f.read() # 2. 配置扩展 # 开启表格合集 自动目录 代码高亮 my_extensions [extra, toc, codehilite] # 扩展配置代码块显示行号 ext_config { codehilite: {linenums: True, css_class: codehilite} } # 3. 转换HTML正文 body_html markdown.markdown( md_text, extensionsmy_extensions, extension_configsext_config ) # 4. 拼接完整HTML页面内嵌CSS样式 full_html f !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的Markdown文档/title style /* 全局基础样式 */ body {{ max-width: 900px; margin: 30px auto; padding: 0 20px; font-family: Microsoft YaHei, 微软雅黑, sans-serif; line-height: 1.7; color: #333; background-color: #fafafa; }} /* 标题样式 */ h1, h2, h3, h4 {{ color: #2c3e50; border-bottom: 1px solid #e0e0e0; padding-bottom: 6px; margin-top: 30px; }} h1 {{ text-align: center; border-bottom: 2px solid #3498db; padding-bottom: 10px; }} /* 段落与引用 */ p {{ margin: 15px 0; }} blockquote {{ border-left: 4px solid #3498db; padding: 10px 15px; margin: 15px 0; background: #f0f7ff; color: #555; }} /* 列表样式 */ ul, ol {{ padding-left: 25px; }} li {{ margin: 5px 0; }} /* 表格样式 */ table {{ border-collapse: collapse; width: 100%; margin: 20px 0; }} th, td {{ border: 1px solid #d0d0d0; padding: 8px 12px; text-align: left; }} th {{ background-color: #3498db; color: white; }} tr:nth-child(even) {{ background-color: #f5f5f5; }} /* 代码块样式 */ .codehilite {{ background: #282c34; color: #abb2bf; padding: 15px; border-radius: 6px; overflow-x: auto; font-size: 14px; margin: 15px 0; }} .codehilite .linenodiv {{ padding-right: 12px; color: #666; border-right: 1px solid #444; margin-right: 10px; }} /* 目录样式 */ .toc {{ background: #fff; border: 1px solid #e0e0e0; border-radius: 6px; padding: 15px 20px; margin: 20px 0; }} .toc ul {{ margin: 5px 0; }} .toc a {{ color: #3498db; text-decoration: none; }} .toc a:hover {{ text-decoration: underline; }} /* 图片自适应 */ img {{ max-width: 100%; border-radius: 4px; }} /style /head body {body_html} /body /html # 5. 保存最终HTML文件 with open(我的笔记_美化版.html, w, encodingutf-8) as f: f.write(full_html) print(转换完成已生成美化版HTML文件)代码说明用f-string把转换好的 HTML 正文嵌入到完整的网页模板中内嵌了一套通用的 Markdown 样式覆盖标题、表格、代码、目录、引用等所有常用元素生成的文件双击就能用浏览器打开排版美观支持目录跳转、代码高亮新手可以直接套用只需要修改输入的 md 文件名和标题即可五、其他可选方案简介除了Python-Markdown还有两个常用的库适合特定场景mistune特点纯 Python 实现解析速度极快轻量无依赖适用场景对性能要求高、只需要基础转换的场景安装pip install mistunemarkdown-it-py特点严格遵循 CommonMark 规范功能丰富插件生态完善适用场景需要更严谨的语法解析、现代文档工具比如 MyST 文档安装pip install markdown-it-py新手建议先把Python-Markdown用熟满足绝大多数场景需求后续有特殊需求再换其他库。六、新手高频踩坑总结表格不生效99% 是没开启extra扩展原生不支持表格语法。中文乱码读写文件必须加encodingutf-8Windows 默认 GBK 编码会导致乱码。代码高亮没颜色没装pygments依赖库只开了扩展没加对应的 CSS 样式扩展只负责加类名颜色需要 CSS 控制目录不显示没开toc扩展Markdown 正文里没写[TOC]标记扩展名拼写错误注意是codehilite不是codehighlight少一个字母都不会生效。七、核心总结基础用法markdown.markdown(md文本)一键转换字符串和文件两种场景都支持进阶必备开启extra扩展解锁表格、脚注等功能是日常使用的标配实用扩展toc自动生成目录、codehilite代码高亮长文档必备最终效果内嵌 CSS 样式生成完整网页打开直接可用新手可以直接套用模板 Python进阶教程：24_Markdown 转 HTML 零基础超详细教程
在 Python 中把 Markdown 文本转换成 HTML 网页最经典、最常用的工具是Python-Markdown第三方库。它完全兼容标准 Markdown 语法还可以通过「扩展插件」解锁表格、代码高亮、自动目录、脚注等进阶功能非常适合生成技术文档、博客页面、笔记导出等场景新手几分钟就能上手。本文从环境搭建、基础转换、进阶扩展到完整实战全程配可运行代码 逐行解释零基础也能做出美观的 HTML 文档。一、环境准备1. 安装库markdown是第三方库需要通过 pip 安装打开终端执行pip install markdown2. 验证安装执行下面的代码不报错就说明安装成功import markdown print(markdown.__version__)补充说明它的核心作用输入 Markdown 格式的文本 / 文件输出对应的 HTML 标签字符串原生只支持基础 Markdown 语法进阶功能需要开启对应的「扩展」可以理解为官方插件生成的默认 HTML 只有标签没有样式需要自己加 CSS 才能变成美观的页面二、基础入门两种核心转换方式方式 1字符串转换内存中直接转适合处理短文本、动态生成的 Markdown 内容直接在内存里转换不需要读写文件。完整示例# 1. 导入库 import markdown # 2. 准备一段Markdown格式的文本 md_text # Python 入门教程 这是一篇用Markdown写的教程**加粗强调重点***斜体标注说明*。 ## 一、基础语法 学习Python需要掌握以下内容 - 变量与数据类型 - 条件判断与循环 - 函数与模块 ## 二、学习建议 多写代码多练习参考官方文档 [Python官方网站](https://www.python.org/) 提示坚持每天练习进步会很快。 # 3. 核心方法把Markdown转换成HTML # markdown.markdown(markdown文本) 返回HTML字符串 html_text markdown.markdown(md_text) # 4. 打印转换结果 print(转换后的HTML内容) print(html_text)运行结果简化h1Python 入门教程/h1 p这是一篇用Markdown写的教程strong加粗强调重点/strongem斜体标注说明/em。/p h2一、基础语法/h2 p学习Python需要掌握以下内容/p ul li变量与数据类型/li li条件判断与循环/li li函数与模块/li /ul ...代码解释markdown.markdown()是最核心的转换函数输入 Markdown 字符串输出 HTML 字符串自动对应关系#转h1、**转strong、-转ulli、转blockquote原生支持所有基础 Markdown 语法标题、段落、加粗、斜体、列表、引用、链接、图片、分割线方式 2本地文件转换.md 转 .html这是日常最常用的场景读取本地已经写好的.md文件转换后保存成.html网页文件。完整示例import markdown # 第一步读取本地Markdown文件 # 必须指定 encodingutf-8否则中文会乱码 with open(我的笔记.md, r, encodingutf-8) as f: # 读取文件全部内容得到Markdown字符串 md_content f.read() # 第二步转换为HTML # 这里先演示基础转换后面会讲解扩展参数 html_content markdown.markdown(md_content) # 第三步保存为HTML文件 with open(我的笔记.html, w, encodingutf-8) as f: f.write(html_content) print(转换完成已生成 我的笔记.html)关键说明中文乱码问题读写文件必须加encodingutf-8这是新手 100% 会踩的坑转换后得到的只是 HTML 正文片段没有head、body等完整页面结构浏览器也能打开但样式很简陋后面的实战部分会教你加上样式生成完整美观的网页三、核心进阶扩展插件Extensions原生markdown只支持最基础的 Markdown 语法表格、任务列表、代码高亮、自动目录这些常用功能都需要开启对应的扩展插件才能使用。这是新手最容易踩坑的地方 —— 写了表格语法却不生效大概率是没开扩展。使用方法在markdown.markdown()方法中加extensions参数传入扩展名称的列表即可html markdown.markdown(md_text, extensions[扩展1, 扩展2])最常用的 5 个扩展1.extra全能扩展合集新手必开这是最常用的扩展一次性打包了表格、脚注、定义列表、属性列表等高频功能日常使用开这一个就够了。示例Markdown 表格转换import markdown md_table ### 学生成绩表 | 姓名 | 年龄 | 分数 | |------|------|------| | 小明 | 18 | 95 | | 小红 | 17 | 88 | | 小刚 | 19 | 92 | # ❌ 不开扩展表格会被当成普通文本格式错乱 # html1 markdown.markdown(md_table) # ✅ 开启extra扩展正确转换成标准table表格标签 html2 markdown.markdown(md_table, extensions[extra]) print(html2)开启后会自动生成带table、tr、th、td的标准表格 HTML 代码。2.toc自动生成目录自动根据文章的标题层级生成带锚点的目录只需要在 Markdown 里写[TOC]标记转换时会自动替换成目录。示例import markdown md_text [TOC] # 第一章Python基础 ## 1.1 变量 变量的定义与使用 ## 1.2 数据类型 常见数据类型介绍 # 第二章函数 ## 2.1 函数定义 def关键字的用法 # 开启toc扩展 html markdown.markdown(md_text, extensions[toc]) print(html)效果[TOC]的位置会被替换成嵌套的目录列表点击目录标题可以跳转到对应章节非常适合长文档。3.codehilite代码块语法高亮给代码块加上语法高亮颜色让代码更易读。需要先安装依赖库pygmentspip install pygments示例import markdown md_code 下面是一段Python代码 python def add(a, b): # 计算两数之和 return a b print(add(1, 2))开启 codehilite 扩展linenumsTrue 表示显示行号html markdown.markdown( md_code, extensions[codehilite], extension_configs{ codehilite: {linenums: True} } ) 注意这个扩展只会给代码标签加上 CSS 类名不会自带颜色需要额外引入高亮样式文件后面完整实战会教你加样式。 --- #### 4. nl2br换行自动转换行标签 标准 Markdown 里单回车不会换行必须空一行才会分段。开启 nl2br 后每一个回车都会自动转换成 br 换行标签适合习惯写短行、随手回车的场景。 python html markdown.markdown(md_text, extensions[nl2br])5.sane_lists智能列表优化列表的解析逻辑避免混合有序 / 无序列表时出现格式错乱让解析结果更符合直觉。四、完整实战生成带样式的美观 HTML默认转换出来的 HTML 只有标签没有任何样式打开非常简陋。我们可以给它加上基础 CSS 样式生成一个排版美观、带代码高亮、带目录的完整网页新手可以直接套用这个模板。完整代码import markdown # 1. 读取Markdown文件 with open(我的笔记.md, r, encodingutf-8) as f: md_text f.read() # 2. 配置扩展 # 开启表格合集 自动目录 代码高亮 my_extensions [extra, toc, codehilite] # 扩展配置代码块显示行号 ext_config { codehilite: {linenums: True, css_class: codehilite} } # 3. 转换HTML正文 body_html markdown.markdown( md_text, extensionsmy_extensions, extension_configsext_config ) # 4. 拼接完整HTML页面内嵌CSS样式 full_html f !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的Markdown文档/title style /* 全局基础样式 */ body {{ max-width: 900px; margin: 30px auto; padding: 0 20px; font-family: Microsoft YaHei, 微软雅黑, sans-serif; line-height: 1.7; color: #333; background-color: #fafafa; }} /* 标题样式 */ h1, h2, h3, h4 {{ color: #2c3e50; border-bottom: 1px solid #e0e0e0; padding-bottom: 6px; margin-top: 30px; }} h1 {{ text-align: center; border-bottom: 2px solid #3498db; padding-bottom: 10px; }} /* 段落与引用 */ p {{ margin: 15px 0; }} blockquote {{ border-left: 4px solid #3498db; padding: 10px 15px; margin: 15px 0; background: #f0f7ff; color: #555; }} /* 列表样式 */ ul, ol {{ padding-left: 25px; }} li {{ margin: 5px 0; }} /* 表格样式 */ table {{ border-collapse: collapse; width: 100%; margin: 20px 0; }} th, td {{ border: 1px solid #d0d0d0; padding: 8px 12px; text-align: left; }} th {{ background-color: #3498db; color: white; }} tr:nth-child(even) {{ background-color: #f5f5f5; }} /* 代码块样式 */ .codehilite {{ background: #282c34; color: #abb2bf; padding: 15px; border-radius: 6px; overflow-x: auto; font-size: 14px; margin: 15px 0; }} .codehilite .linenodiv {{ padding-right: 12px; color: #666; border-right: 1px solid #444; margin-right: 10px; }} /* 目录样式 */ .toc {{ background: #fff; border: 1px solid #e0e0e0; border-radius: 6px; padding: 15px 20px; margin: 20px 0; }} .toc ul {{ margin: 5px 0; }} .toc a {{ color: #3498db; text-decoration: none; }} .toc a:hover {{ text-decoration: underline; }} /* 图片自适应 */ img {{ max-width: 100%; border-radius: 4px; }} /style /head body {body_html} /body /html # 5. 保存最终HTML文件 with open(我的笔记_美化版.html, w, encodingutf-8) as f: f.write(full_html) print(转换完成已生成美化版HTML文件)代码说明用f-string把转换好的 HTML 正文嵌入到完整的网页模板中内嵌了一套通用的 Markdown 样式覆盖标题、表格、代码、目录、引用等所有常用元素生成的文件双击就能用浏览器打开排版美观支持目录跳转、代码高亮新手可以直接套用只需要修改输入的 md 文件名和标题即可五、其他可选方案简介除了Python-Markdown还有两个常用的库适合特定场景mistune特点纯 Python 实现解析速度极快轻量无依赖适用场景对性能要求高、只需要基础转换的场景安装pip install mistunemarkdown-it-py特点严格遵循 CommonMark 规范功能丰富插件生态完善适用场景需要更严谨的语法解析、现代文档工具比如 MyST 文档安装pip install markdown-it-py新手建议先把Python-Markdown用熟满足绝大多数场景需求后续有特殊需求再换其他库。六、新手高频踩坑总结表格不生效99% 是没开启extra扩展原生不支持表格语法。中文乱码读写文件必须加encodingutf-8Windows 默认 GBK 编码会导致乱码。代码高亮没颜色没装pygments依赖库只开了扩展没加对应的 CSS 样式扩展只负责加类名颜色需要 CSS 控制目录不显示没开toc扩展Markdown 正文里没写[TOC]标记扩展名拼写错误注意是codehilite不是codehighlight少一个字母都不会生效。七、核心总结基础用法markdown.markdown(md文本)一键转换字符串和文件两种场景都支持进阶必备开启extra扩展解锁表格、脚注等功能是日常使用的标配实用扩展toc自动生成目录、codehilite代码高亮长文档必备最终效果内嵌 CSS 样式生成完整网页打开直接可用新手可以直接套用模板