在先前的文章Obsidian 使用之 Markdown 中介绍下 Markdown 语法。今天要梳理的是如何在 Python 中解析和处理 markdown 语法。Python 有几个流行的 Markdown 处理包，可以帮助你将 Markdown 转换为 HTML、PDF，或用于其他格式和功能。
Python-Markdown
Python-Markdown 是一个用于将 Markdown 文本转换为 HTML 的纯 Python 实现。它是一个轻量级的库，支持标准的 Markdown 语法，并提供了许多扩展以增加功能。
特点
- 标准支持: 支持标准的 Markdown 语法，包括标题、列表、链接、图片、代码块等。
- 可扩展性: 提供了一系列内置扩展，并支持自定义扩展以满足特定需求。
- 轻量级和易于使用: 安装和使用都非常简单，适合快速集成到 Python 项目中。
安装
你可以使用 pip 来安装 Python-Markdown：pip install markdown基本用法
以下是一个简单的示例，展示如何将 Markdown 文本转换为 HTML：
import markdown # Markdown 文本 md_text = """ # 标题 这是一个段落，其中包含**加粗文本**和*斜体文本*。 - 列表项 1 - 列表项 2 [链接文本](http://example.com) """ # 将 Markdown 转换为 HTML html = markdown.markdown(md_text) print(html)
扩展
Python-Markdown 提供了一系列内置扩展，可以通过传递 extensions 参数来启用。例如：
import markdown # 启用额外的扩展 html = markdown.markdown(md_text, extensions=['extra', 'codehilite', 'toc']) print(html)
一些常用的扩展包括：
- extra: 提供额外的 Markdown 语法支持，如表格、脚注等。
- codehilite: 用于代码高亮显示。
- toc: 自动生成目录。
- meta: 解析 Markdown 文本中的元数据。
自定义扩展
如果内置扩展不满足需求，可以创建自定义扩展。扩展是通过实现特定的接口来处理 Markdown 文本的不同部分。
以下是一个简单的自定义扩展示例：
from markdown.extensions import Extension
from markdown.preprocessors import Preprocessor
import re
class SimpleExtension(Extension):
def extendMarkdown(self, md):
md.preprocessors.register(SimplePreprocessor(md), 'simple_preprocessor', 25)
class SimplePreprocessor(Preprocessor):
def run(self, lines):
new_lines = []
for line in lines:
# 这里可以自定义处理逻辑
new_lines.append(re.sub(r'\bfoo\b', 'bar', line))
return new_lines
md_text = "This is a foo example."
html = markdown.markdown(md_text, extensions=[SimpleExtension()])
print(html)
PyMdown Extensions
PyMdown Extensions 是 Python-Markdown 库的一组扩展集合，旨在增强 Markdown 的功能和灵活性。这些扩展提供了许多附加功能，允许用户以更丰富的方式格式化和呈现 Markdown 文本。
主要特点
- 增强的 Markdown 功能: 提供了比标准 Markdown 更丰富的语法和功能。
- 易于集成: 与 Python-Markdown 无缝集成，可以通过简单的配置启用。
- 灵活的配置选项: 大多数扩展都支持自定义配置，以满足特定需求。
- 开源和活跃的社区支持: 不断更新和改进，提供良好的文档和支持。
安装
你可以通过 pip 安装 PyMdown Extensions：pip install pymdown-extensions常用扩展
PyMdown Extensions 提供了多种扩展，以下是一些常用的：
- Arithmatex: 支持 LaTeX 数学公式的渲染。
- B64: 允许在 Markdown 中嵌入 Base64 编码的图像。
- Caret: 支持上标和下标文本。
- Critic: 提供文本修订标记功能。
- Emoji: 支持在 Markdown 中使用 Emoji 符号。
- Highlight: 允许对文本进行高亮显示。
- InlineHilite: 支持内联代码的语法高亮。
- MagicLink: 自动将 URL 和电子邮件地址转换为链接。
- Mark: 提供文本标记功能。
- Snippets: 支持 Markdown 中的代码片段重用。
使用示例
以下是一个示例，展示如何使用 PyMdown Extensions 来增强 Markdown 的功能：
import markdown
# Markdown 文本
md_text = """
# 示例
这是一个包含数学公式的段落：$E=mc^2$。
这是一个使用 Emoji 的段落：:smile:
这是一个包含上标和下标的段落：H~2~O 和 x^2^。
"""
# 将 Markdown 转换为 HTML，并启用 PyMdown 扩展
html = markdown.markdown(md_text, extensions=[
'pymdownx.arithmatex',
'pymdownx.emoji',
'pymdownx.caret'
])
print(html)
配置选项
PyMdown Extensions 中的许多扩展都提供了配置选项，可以通过 Python-Markdown 的 extension_configs 参数进行设置。例如：
extension_configs = {
'pymdownx.emoji': {
'emoji_generator': 'twemoji'
}
}
html = markdown.markdown(md_text, extensions=[
'pymdownx.emoji'
], extension_configs=extension_configs)
markdown2
Markdown2 是一个用 Python 编写的快速、轻量级的 Markdown 解析器。它提供了一些扩展功能，使得 Markdown 文本的处理更加灵活和强大。Markdown2 的设计目标是提供一个简单易用的接口，同时保持高性能。markdown2 是 Python-Markdown 的替代品，支持更多扩展特性（如代码高亮、表格等），且 API 简单易用。
主要特点
- 简单易用: 提供了一个简单的 API，便于将 Markdown 文本转换为 HTML。
- 高性能: 相较于一些其他的 Markdown 解析器，Markdown2 在解析速度上表现良好。
- 扩展功能: 支持多种扩展，增强了标准 Markdown 的功能。
- 纯 Python 实现: 易于安装和使用，无需复杂的依赖。
安装
你可以使用 pip 来安装 Markdown2：pip install markdown2基本用法
Markdown2 的基本用法非常简单。以下是一个将 Markdown 文本转换为 HTML 的示例：
import markdown2 # Markdown 文本 md_text = """ # 标题 这是一个段落，其中包含**加粗文本**和*斜体文本*。 - 列表项 1 - 列表项 2 [链接文本](http://example.com) """ # 将 Markdown 转换为 HTML html = markdown2.markdown(md_text) print(html)
扩展
Markdown2 支持多种扩展，可以在转换时启用这些扩展以增强功能。常用的扩展包括：
- fenced-code-blocks: 支持围栏代码块（用 “` 包裹的代码块）。
- footnotes: 支持脚注。
- tables: 支持 Markdown 表格。
- toc: 支持生成目录。
- code-friendly: 改善代码块的处理。
启用扩展的示例：
html = markdown2.markdown(md_text, extras=["fenced-code-blocks", "tables"])
自定义扩展
虽然 Markdown2 不像 Python-Markdown 那样支持复杂的自定义扩展，但它的设计仍然允许用户通过修改源码或利用现有的钩子机制来实现一些定制功能。
Mistune
Mistune 是一个快速、轻量级且高度可扩展的 Markdown 解析器，使用纯 Python 实现。它以其高性能和灵活性著称，适合需要自定义渲染和扩展功能的应用场景。
主要特点
- 高性能: Mistune 在解析速度上表现非常优异，适合对性能有较高要求的项目。
- 高度可扩展: 提供了自定义渲染器和插件机制，用户可以轻松定制 Markdown 解析的行为。
- 符合 CommonMark 标准: 默认情况下，Mistune 遵循 CommonMark 标准，确保 Markdown 文本的一致性解析。
- 轻量级: 设计简单，易于集成和使用。
安装
你可以使用 pip 来安装 Mistune：pip install mistune基本用法
Mistune 的基本用法非常简单，以下是一个将 Markdown 文本转换为 HTML 的示例：
import mistune # 创建一个 Markdown 解析器实例 markdown = mistune.create_markdown() # Markdown 文本 md_text = """ # 标题 这是一个段落，其中包含**加粗文本**和*斜体文本*。 - 列表项 1 - 列表项 2 [链接文本](http://example.com) """ # 将 Markdown 转换为 HTML html = markdown(md_text) print(html)
自定义渲染器
Mistune 支持自定义渲染器，使用户可以完全控制 Markdown 元素的渲染方式。以下是一个简单的自定义渲染器示例：
from mistune import HTMLRenderer, create_markdown
class CustomRenderer(HTMLRenderer):
def heading(self, text, level):
return f'<h{level} style="color:blue;">{text}</h{level}>'
# 使用自定义渲染器创建 Markdown 解析器
markdown = create_markdown(renderer=CustomRenderer())
md_text = "# Custom Heading"
html = markdown(md_text)
print(html) # 输出的标题将使用蓝色
插件机制
Mistune 提供了插件机制，允许用户在解析过程中添加自定义行为。可以通过插件来扩展 Markdown 的功能，例如添加新的语法支持或修改现有的解析逻辑。
Grip
Grip（GitHub Readme Instant Preview）是一个用于即时预览 GitHub 风格的 Markdown 文件的工具。它主要用于本地查看 Markdown 文件的渲染效果，尤其是在编辑 GitHub 项目的 README 文件时非常有用。Grip 提供了一种简单的方法来在本地环境中查看 Markdown 文件的最终效果，而无需将文件推送到 GitHub。
主要特点
- GitHub 风格渲染: 使用 GitHub 的 API 来渲染 Markdown 文件，因此预览效果与 GitHub 上显示的效果一致。
- 即时预览: Grip 启动一个本地 Web 服务器，实时显示 Markdown 文件的渲染效果。每当文件发生更改时，页面会自动刷新。
- 简单易用: 使用简单，只需一个命令即可启动预览。
- 支持私有仓库: 可以通过配置 GitHub API 令牌来预览私有仓库中的 Markdown 文件。
安装
你可以使用 pip 来安装 Grip：pip install grip基本用法
Grip 的使用非常简单。以下是如何使用 Grip 预览 Markdown 文件的步骤：
- 在终端中导航到包含 Markdown 文件的目录。
- 运行以下命令启动 Grip：grip README.md
这里的 README.md 可以替换为你想要预览的 Markdown 文件。Grip 会启动一个本地 Web 服务器（默认端口为 6419），你可以在浏览器中访问 http://localhost:6419 来查看 Markdown 文件的渲染效果。
PyPandoc
PyPandoc 是一个 Python 库，提供了一个接口用于调用 Pandoc。Pandoc 是一个强大的文档转换工具，支持多种文档格式之间的转换。PyPandoc 简化了在 Python 环境中使用 Pandoc 的过程，使得用户可以轻松地在 Python 脚本中执行复杂的文档格式转换。
主要特点
- 多格式支持: 利用 Pandoc 的强大功能，支持多种文档格式之间的转换，包括 Markdown、HTML、PDF、DOCX、LaTeX 等。
- 易于集成: 提供简单的 Python 接口，可以轻松集成到 Python 项目中。
- 跨平台: 支持在 Windows、macOS 和 Linux 上运行。
- 灵活的选项: 支持 Pandoc 的各种命令行选项，允许用户对转换过程进行精细控制。
安装
要使用 PyPandoc，你需要先安装 Pandoc。可以从Pandoc的官方网站下载并安装适合你操作系统的版本。
安装完成后，可以使用 pip 安装 PyPandoc：pip install pypandoc
PyPandoc的基本用法非常简单，以下是一些常见的用例：
文本转换
将 Markdown 转换为 HTML：
import pypandoc # Markdown文本 markdown_text = "# Hello World\nThis is a paragraph." # 转换为 HTML html_text = pypandoc.convert_text(markdown_text, 'html', format='md') print(html_text)
文件转换
将 Markdown 文件转换为 PDF：
import pypandoc
# 将 Markdown 文件转换为 PDF
output = pypandoc.convert_file('example.md', 'pdf', outputfile='example.pdf')
# output 为 None，因为结果已经写入到文件
print(output)
支持的格式
可以通过以下命令查看 Pandoc 支持的输入和输出格式：
import pypandoc print(pypandoc.get_pandoc_formats())
选项和过滤器
PyPandoc 支持传递 Pandoc 的命令行选项和使用自定义过滤器。例如：
import pypandoc # 使用 Pandoc 选项 html_text = pypandoc.convert_text( "# Hello World", 'html', format='md', extra_args=['--standalone'] ) print(html_text)
注意事项
- Pandoc 的安装: 确保 Pandoc 已正确安装并且在系统路径中可用，因为 PyPandoc 依赖于 Pandoc 来执行转换。
- 版本兼容性: 不同版本的 Pandoc 可能会有不同的功能和选项，确保 PyPandoc 和 Pandoc 版本的兼容性。
- 性能: 对于大文件或复杂的转换，性能可能会受到影响，建议在这些情况下进行性能测试和优化。
html2text
html2text 是一个用于将 HTML 内容转换为纯文本格式的 Python 库。它的主要目标是保留 HTML 文档的结构和可读性，同时去除所有 HTML 标签，使得输出的文本可以方便地用于电子邮件、日志文件或其他需要纯文本的场景。html2text 是一个开源项目，广泛用于需要从 HTML 中提取可读文本的应用程序中。
基本用法
html2text 提供了一个简单的接口，可以轻松地将 HTML 转换为纯文本。以下是一些基本用法示例：
import html2text html_content = """ <h1>Example Title</h1> <p>This is a <strong>sample</strong> paragraph with <a href="https://example.com">a link</a>.</p> """ # 创建转换器对象 converter = html2text.HTML2Text() # 转换 HTML 到文本 text = converter.handle(html_content) print(text)
输出结果：
Example Title ============= This is a **sample** paragraph with [a link](https://example.com).
高级功能
html2text 提供了一些选项，可以用于自定义转换行为：
- 忽略链接：如果不需要在文本中保留链接，可以设置 ignore_links 为 True。
- 忽略图像：如果不需要在文本中保留图像描述，可以设置 ignore_images 为 True。
- 保留空行：可以通过设置 body_width 为 0 来禁用自动换行。
- 单独处理标题：通过设置 single_line_break 为 True，可以在标题后只使用一个换行符。
converter.ignore_links = True converter.ignore_images = True converter.body_width = 0 converter.single_line_break = True
使用命令行工具
html2text 也提供了一个命令行工具，可以直接在终端中使用：
html2text input.html > output.txt
这将读取 input.html 文件，并将转换后的文本写入 output.txt 文件中。
