Python Markdown 生成 HTML（完整教程）

快速解决

要将 Markdown 文件转换为 HTML，可以直接使用 Python 中的 markdown 模块。只需一行代码即可完成转换：

import markdown
html = markdown.markdown("## 标题\n内容")  # 将 Markdown 文本转为 HTML

此方法适用于快速将 Markdown 格式的文本内容生成 HTML 字符串，常用于动态生成网页内容、文档转换等场景。

常用方法

以下是几种常用的 Python Markdown 生成 HTML 的方法和工具：

方法	功能	示例
`markdown.markdown(text)`	将 Markdown 字符串转为 HTML	`markdown.markdown("## 标题")`
`markdown.markdownFromFile(input, output)`	读取 Markdown 文件并写入 HTML 文件	`markdown.markdownFromFile("input.md", "output.html")`
`markdown2.markdown(text)`	另一个流行的 Markdown 解析库，功能更全	`markdown2.markdown("## 标题")`
`pandoc`（通过 Python 调用）	强大的文档转换工具，支持 Markdown 到 HTML 的高级转换	`subprocess.run(["pandoc", "input.md", "-o", "output.html"])`
`jinja2` + Markdown	用于构建网页模板，结合 Markdown 使用	在模板中渲染 Markdown 内容
`mistune`	快速且轻量的 Markdown 解析器	`mistune.markdown("## 标题")`

详细说明

使用标准库 markdown

Python 标准库中的 markdown 模块是最基础的 Markdown 转换工具。它将 Markdown 文本转换为 HTML 字符串。

import markdown

md_text = "# 标题\n\n这是一个段落。"

html_content = markdown.markdown(md_text)

print(html_content)

使用 markdown2

markdown2 是另一个流行的 Markdown 解析库，相比标准库的 markdown，它提供了更丰富的语法支持和更好的扩展性。

import markdown2

md_text = "## 标题\n\n这是一个*斜体*和**加粗**的段落。"

html_content = markdown2.markdown(md_text)

print(html_content)

使用 subprocess 调用 pandoc

pandoc 是一个功能强大的文档转换工具，支持多种格式。通过 Python 的 subprocess 模块，我们可以调用它来将 Markdown 文件转为 HTML。

import subprocess

subprocess.run(["pandoc", "example.md", "-o", "output.html"])

高级技巧

自定义 HTML 输出格式

通过 markdown 模块的 extensions 参数，可以启用扩展功能，如添加 HTML 标签、生成 TOC（目录）等：

import markdown

html = markdown.markdown(
    "# 标题\n\n## 小标题1\n\n## 小标题2",
    extensions=["toc"],
    output_format="html5"
)

print(html)

结合 Jinja2 模板使用

在 Web 开发中，常使用 Jinja2 模板引擎渲染 HTML 页面。可以将 Markdown 内容作为变量传入模板，再由模板渲染成完整的 HTML 页面：

from jinja2 import Template
import markdown

md_content = "## 页面内容\n\n这是由 Jinja2 模板渲染的 Markdown。"

html_content = markdown.markdown(md_content)

template = Template("""
<!DOCTYPE html>
<html>
<head><title>Markdown 转 HTML</title></head>
<body>
{{ content|safe }}
</body>
</html>
""")

result = template.render(content=html_content)

print(result)

常见问题

Q1：转换后的 HTML 为什么没有样式？
A：Markdown 只处理内容结构，不包含样式。需要手动添加 CSS 或使用工具生成带样式的 HTML。

Q2：如何保留 Markdown 中的 HTML 标签？
A：使用 markdown.markdown(text, output_format="html5") 可以保留 HTML 标签，但默认会过滤一些不安全标签。

Q3：如何批量转换多个 Markdown 文件为 HTML？
A：可以使用 os.listdir() 遍历目录，结合 markdown.markdownFromFile() 逐个转换，或使用 pandoc 命令行批量处理。

Q4：为什么有些 Markdown 语法没被正确解析？
A：不同 Markdown 解析库支持的语法可能不同。建议统一使用一个库，并阅读其文档确认支持的语法。

实战应用

在实际开发中，Markdown 生成 HTML 的需求常见于以下场景：

静态网站生成器：如使用 MkDocs 或 Pelican，将 Markdown 文档编译为 HTML 网站。
文档自动化生成：在 CI/CD 流程中，将 Markdown 格式的 API 文档自动生成 HTML。
博客平台后台处理：用户用 Markdown 编写内容，系统在发布时将其转为 HTML。

下面是一个完整的 Markdown 转 HTML 的示例，适用于从文件读取并输出到 HTML：

import markdown

with open("input.md", "r", encoding="utf-8") as file:
    md_text = file.read()

html = markdown.markdown(md_text, output_format="html5")

with open("output.html", "w", encoding="utf-8") as file:
    file.write(html)

注意事项

Markdown 语法不统一，不同工具支持略有差异，建议选择一个工具并坚持使用。
转换 HTML 后，务必验证生成的 HTML 结构是否符合预期。
使用第三方库时，注意版本兼容性，避免出现解析错误。
若 Markdown 中包含复杂结构（如表格、脚注），建议使用支持扩展的库（如 markdown2 或 pandoc）。