在 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)运行结果（简化）
<h1>Python 入门教程</h1> <p>这是一篇用Markdown写的教程，<strong>加粗强调重点</strong>，<em>斜体标注说明</em>。</p> <h2>一、基础语法</h2> <p>学习Python需要掌握以下内容：</p> <ul> <li>变量与数据类型</li> <li>条件判断与循环</li> <li>函数与模块</li> </ul> ...代码解释
markdown.markdown()是最核心的转换函数，输入 Markdown 字符串，输出 HTML 字符串- 自动对应关系：
#转<h1>、**转<strong>、-转<ul><li>、>转<blockquote> - 原生支持所有基础 Markdown 语法：标题、段落、加粗、斜体、列表、引用、链接、图片、分割线
方式 2：本地文件转换（.md 转 .html）
这是日常最常用的场景：读取本地已经写好的.md文件，转换后保存成.html网页文件。
完整示例
import markdown # ========== 第一步：读取本地Markdown文件 ========== # 必须指定 encoding="utf-8"，否则中文会乱码 with open("我的笔记.md", "r", encoding="utf-8") as f: # 读取文件全部内容，得到Markdown字符串 md_content = f.read() # ========== 第二步：转换为HTML ========== # 这里先演示基础转换，后面会讲解扩展参数 html_content = markdown.markdown(md_content) # ========== 第三步：保存为HTML文件 ========== with open("我的笔记.html", "w", encoding="utf-8") as f: f.write(html_content) print("转换完成！已生成 我的笔记.html")关键说明
- 中文乱码问题：读写文件必须加
encoding="utf-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：代码块语法高亮
给代码块加上语法高亮颜色，让代码更易读。需要先安装依赖库pygments：
pip install pygments示例
import markdown md_code = """ 下面是一段Python代码： ```python def add(a, b): # 计算两数之和 return a + b print(add(1, 2))"""
开启 codehilite 扩展，linenums=True 表示显示行号
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", encoding="utf-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, extensions=my_extensions, extension_configs=ext_config ) # ========== 4. 拼接完整HTML页面（内嵌CSS样式） ========== full_html = f""" <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.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", encoding="utf-8") as f: f.write(full_html) print("转换完成！已生成美化版HTML文件")代码说明
- 用
f-string把转换好的 HTML 正文嵌入到完整的网页模板中 - 内嵌了一套通用的 Markdown 样式，覆盖标题、表格、代码、目录、引用等所有常用元素
- 生成的文件双击就能用浏览器打开，排版美观，支持目录跳转、代码高亮
- 新手可以直接套用，只需要修改输入的 md 文件名和标题即可
五、其他可选方案简介
除了Python-Markdown，还有两个常用的库，适合特定场景：
- mistune
- 特点：纯 Python 实现，解析速度极快，轻量无依赖
- 适用场景：对性能要求高、只需要基础转换的场景
- 安装：
pip install mistune
- markdown-it-py
- 特点：严格遵循 CommonMark 规范，功能丰富，插件生态完善
- 适用场景：需要更严谨的语法解析、现代文档工具（比如 MyST 文档）
- 安装：
pip install markdown-it-py
新手建议：先把
Python-Markdown用熟，满足绝大多数场景需求，后续有特殊需求再换其他库。
六、新手高频踩坑总结
- 表格不生效99% 是没开启
extra扩展，原生不支持表格语法。 - 中文乱码读写文件必须加
encoding="utf-8"，Windows 默认 GBK 编码会导致乱码。 - 代码高亮没颜色
- 没装
pygments依赖库 - 只开了扩展没加对应的 CSS 样式，扩展只负责加类名，颜色需要 CSS 控制
- 没装
- 目录不显示
- 没开
toc扩展 - Markdown 正文里没写
[TOC]标记
- 没开
- 扩展名拼写错误注意是
codehilite不是codehighlight，少一个字母都不会生效。
七、核心总结
- 基础用法：
markdown.markdown(md文本)一键转换，字符串和文件两种场景都支持 - 进阶必备：开启
extra扩展解锁表格、脚注等功能，是日常使用的标配 - 实用扩展：
toc自动生成目录、codehilite代码高亮，长文档必备 - 最终效果：内嵌 CSS 样式生成完整网页，打开直接可用，新手可以直接套用模板
