Python进阶教程：24_Markdown 转 HTML 零基础超详细教程

在 Python 中把 Markdown 文本转换成 HTML 网页，最经典、最常用的工具是 Python-Markdown 第三方库。它完全兼容标准 Markdown 语法，还可以通过「扩展插件」解锁表格、代码高亮、自动目录、脚注等进阶功能，非常适合生成技术文档、博客页面、笔记导出等场景，新手几分钟就能上手。

本文从环境搭建、基础转换、进阶扩展到完整实战，全程配可运行代码 + 逐行解释，零基础也能做出美观的 HTML 文档。

一、环境准备

1. 安装库

markdown 是第三方库，需要通过 pip 安装，打开终端执行：

复制代码

pip install markdown

2. 验证安装

执行下面的代码，不报错就说明安装成功：

复制代码

import markdown
print(markdown.__version__)

补充说明

它的核心作用：输入 Markdown 格式的文本 / 文件，输出对应的 HTML 标签字符串
原生只支持基础 Markdown 语法，进阶功能需要开启对应的「扩展」（可以理解为官方插件）
生成的默认 HTML 只有标签没有样式，需要自己加 CSS 才能变成美观的页面

二、基础入门：两种核心转换方式

方式 1：字符串转换（内存中直接转）

适合处理短文本、动态生成的 Markdown 内容，直接在内存里转换，不需要读写文件。

完整示例

python 复制代码

# 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)

运行结果（简化）

python 复制代码

<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 网页文件。

完整示例

python 复制代码

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 参数，传入扩展名称的列表即可：

python 复制代码

html = markdown.markdown(md_text, extensions=["扩展1", "扩展2"])

最常用的 5 个扩展

1. `extra`：全能扩展合集（新手必开）

这是最常用的扩展，一次性打包了表格、脚注、定义列表、属性列表等高频功能，日常使用开这一个就够了。

示例：Markdown 表格转换

python 复制代码

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] 标记，转换时会自动替换成目录。

示例

python 复制代码

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

示例

python 复制代码

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} } )

python 复制代码

> 注意：这个扩展只会给代码标签加上 CSS 类名，不会自带颜色，需要额外引入高亮样式文件，后面完整实战会教你加样式。

---
#### 4. `nl2br`：换行自动转换行标签
标准 Markdown 里，单回车不会换行，必须空一行才会分段。开启 `nl2br` 后，每一个回车都会自动转换成 `<br>` 换行标签，适合习惯写短行、随手回车的场景。

```python
html = markdown.markdown(md_text, extensions=["nl2br"])

5. `sane_lists`：智能列表

优化列表的解析逻辑，避免混合有序 / 无序列表时出现格式错乱，让解析结果更符合直觉。

四、完整实战：生成带样式的美观 HTML

默认转换出来的 HTML 只有标签，没有任何样式，打开非常简陋。我们可以给它加上基础 CSS 样式，生成一个排版美观、带代码高亮、带目录的完整网页，新手可以直接套用这个模板。

完整代码

python 复制代码

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 样式生成完整网页，打开直接可用，新手可以直接套用模板

Python进阶教程：24_Markdown 转 HTML 零基础超详细教程

一、环境准备

1. 安装库

2. 验证安装

补充说明

二、基础入门：两种核心转换方式

方式 1：字符串转换（内存中直接转）

完整示例

运行结果（简化）

代码解释

方式 2：本地文件转换（.md 转 .html）

完整示例

关键说明

三、核心进阶：扩展插件（Extensions）

使用方法

最常用的 5 个扩展

1. extra：全能扩展合集（新手必开）

示例：Markdown 表格转换

2. toc：自动生成目录

示例

3. codehilite：代码块语法高亮

示例

开启 codehilite 扩展，linenums=True 表示显示行号

5. sane_lists：智能列表

四、完整实战：生成带样式的美观 HTML

完整代码

代码说明

五、其他可选方案简介

六、新手高频踩坑总结

七、核心总结

1. `extra`：全能扩展合集（新手必开）

2. `toc`：自动生成目录

3. `codehilite`：代码块语法高亮

5. `sane_lists`：智能列表