markdown: 最基础、最核心的 Markdown 到 HTML 的转换库。Mistune: 一个更快、更轻量级、更安全的解析器,性能极高。Python-Markdown: 这其实是第一个库markdown的全称和官方 PyPI 包名，为了避免混淆，我们直接用markdown这个名称。
还会介绍一个更高级的库 MkDocs，它是一个完整的文档站点生成工具，内部也使用了 Markdown。
核心库：markdown (Python-Markdown)
这是最常用、最标准的库，功能强大,扩展性好。
安装
你需要安装它：
pip install markdown
基本用法
这个库的核心功能就是将 Markdown 字符串转换为 HTML 字符串。
import markdown
# 1. 准备你的 Markdown 文本
md_text = """
# 这是一级标题
这是一个 **粗体** 和 *斜体* 的例子。
- 列表项 1
- 列表项 2
- 嵌套列表项
> 这是一个引用块。
```python
# 代码块
def hello():
print("Hello, Markdown!")
这是一个链接 """
使用 markdown.markdown() 函数进行转换
默认情况下，它会启用一些基础扩展
html_output = markdown.markdown(md_text)
输出结果
print(html_output)
**输出结果：**
```html
<h1>这是一级标题</h1>
<p>这是一个 <strong>粗体</strong> 和 <em>斜体</em> 的例子。</p>
<ul>
<li>列表项 1</li>
<li>列表项 2
<ul>
<li>嵌套列表项</li>
</ul>
</li>
</ul>
<blockquote>
<p>这是一个引用块。</p>
</blockquote>
<pre><code class="language-python"># 代码块
def hello():
print("Hello, Markdown!")
</code></pre>
<p><a href="https://www.python.org">这是一个链接</a></p>高级用法：扩展
markdown 库的强大之处在于它的扩展系统，你可以通过 extensions 参数来启用额外的功能。
常用扩展：
fenced_code: 支持使用 ``` ``` 来创建代码块，并可以指定语言（如上面的例子）。codehilite: 为代码块添加语法高亮（需要配合Pygments库）。tables: 支持创建表格。toc(Table of Contents): 自动生成目录。nl2br: 将单个换行符转换为<br>
示例：启用表格和代码高亮
-
先安装
Pygments：pip install Pygments
-
在代码中使用：
import markdown
md_text_with_table = """
| 姓名 | 年龄 | 职业 |
|------|------|------|
| 张三 | 28 | 工程师 |
| 李四 | 32 | 设计师 |
"""
# 启用表格扩展
html_table = markdown.markdown(md_text_with_table, extensions=['tables'])
print("--- 表格扩展 ---")
print(html_table)
md_text_with_code = """
```python
def greet(name):
return f"Hello, {name}!"
启用代码高亮扩展
注意：这需要 CSS 样式才能在浏览器中正确显示颜色
html_codehilite = markdown.markdown(md_text_with_code, extensions=['codehilite']) print("\n--- 代码高亮扩展 ---") print(html_codehilite)
**输出结果：**
```html
--- 表格扩展 ---
<table>
<thead>
<tr>
<th>姓名</th>
<th>年龄</th>
<th>职业</th>
</tr>
</thead>
<tbody>
<tr>
<td>张三</td>
<td>28</td>
<td>工程师</td>
</tr>
<tr>
<td>李四</td>
<td>32</td>
<td>设计师</td>
</tr>
</tbody>
</table>
--- 代码高亮扩展 ---
<div class="highlight"><pre><span></span><code><span class="k">def</span> <span class="nf">greet</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="k">return</span> <span class="sa">f</span><span class="s2">"Hello, </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">!"</span>
</code></pre></div>高性能库：Mistune
如果你对性能有极致要求，比如需要处理大量 Markdown 文件或在 Web 框架中高频使用，Mistune 是一个绝佳的选择，它的解析速度比 markdown 快很多。
安装
pip install mistune
基本用法
Mistune 的 API 更简洁，直接调用 mistune.markdown() 即可。
import mistune md_text = """ **粗体文本**。 """ html_output = mistune.markdown(md_text) print(html_output)
输出结果：
<p><strong>粗体文本</strong>。</p>高级用法：渲染器和插件
Mistune 提供了更底层的控制，比如你可以自定义渲染器来输出不同的格式（不仅仅是 HTML），或者使用插件（类似 markdown 的扩展）。
示例：使用插件
import mistune from mistune.plugins import plugin_table, plugin_url md_text_with_table = """ | Header 1 | Header 2 | |----------|----------| | Cell 1 | Cell 2 | | [链接](https://example.com) | Cell 4 | """ # 创建一个带有表格和链接扩展的渲染器 renderer = mistune.HTMLRenderer() # mistune 内置了对表格和链接等常见 Markdown 元素的支持， # 所以这里直接使用 markdown 函数即可，它会自动处理。 # 如果需要更精细的控制，可以手动创建渲染器并添加插件。 html_output = mistune.markdown(md_text_with_table, plugins=[plugin_table]) print(html_output)
完整文档站点工具：MkDocs
如果你不仅仅是想转换单个 Markdown 文件，而是想构建一个像官方文档那样的静态网站，MkDocs 是你的不二之选，它使用 Markdown 作为源文件,并可以轻松地生成美观的网站。
安装
pip install mkdocs
基本用法
-
初始化项目： 在你的项目目录下运行：
mkdocs new my-docs
这会创建一个
my-docs文件夹，里面包含一个docs文件夹（存放你的.md文件）和一个mkdocs.yml配置文件。 -
编写文档： 在
docs文件夹中编写你的 Markdown 文件，index.md。 -
本地预览： 在
my-docs目录下运行：mkdocs serve
然后打开浏览器访问
http://127.0.0.1:8000，你就能看到一个由 Markdown 生成的网站。 -
部署到 GitHub Pages：
MkDocs与 GitHub Pages 集成得非常好,一条命令即可部署：mkdocs gh-deploy
MkDocs 内部使用了 markdown 库，并默认启用了一些扩展，同时提供了强大的主题系统（如 mkdocs-material 主题）。
总结与对比
| 特性 | markdown (Python-Markdown) |
Mistune |
MkDocs |
|---|---|---|---|
| 主要用途 | 将 Markdown 字符串转换为 HTML | 将 Markdown 字符串转换为 HTML | 构建完整的 Markdown 文档站点 |
| 性能 | 良好 | 非常高 | 依赖内部引擎，整体构建速度不错 |
| 易用性 | 非常简单，API 直观 | 非常简单，API 更底层 | 需要学习配置文件 mkdocs.yml |
| 扩展性 | 非常强，丰富的扩展生态 | 强，通过插件和自定义渲染器 | 强，通过插件和主题 |
| 输出格式 | 主要是 HTML | 主要是 HTML，可自定义 | HTML 网站 |
| 适用场景 | - 在脚本中处理 Markdown - Web 框架（如 Flask, Django）的后端渲染 - 需要快速转换的场景 |
- 对性能要求极高的应用 - 需要自定义输出格式的场景 |
- 项目文档 - 技术博客 - API 文档 |
| 依赖 | 基础库，扩展可选 | 基础库，插件可选 | mkdocs 本身，可选主题和插件 |
如何选择？
- 如果你只是想在 Python 脚本里把一小段 Markdown 转成 HTML：用
markdown，它最标准，文档最全，能满足 90% 的需求。 - 如果你在做一个性能敏感的应用，比如一个高并发的 Web 服务，需要实时渲染 Markdown：用
Mistune,它的速度优势会很明显。 - 如果你想为你的项目（Python 库、开源软件）创建一个漂亮的官方文档网站：用
MkDocs，它为你解决了所有关于网站结构、导航、样式和部署的麻烦，让你专注于写 Markdown 内容。
希望这个详细的解释能帮助你理解 Python 中 Markdown 的用法！
