参考 Python-Markdown — Python-Markdown 3.3.3 documentation (python-markdown.github.io)

1 Python-Markdown 简述

Python-Markdown 是 John Gruber 的 Markdown 的 Python 实现。它几乎完全符合引用实现，尽管存在一些已知问题。有关支持的确切是什么和不支持哪些功能的信息，请参阅 Features。Available Extensions支持其他功能。

安装：

pip install markdown

2 使用 markdown 作为 Python 库

import markdown
html = markdown.markdown(your_text_string)

Python-Markdown 提供了两个函数：markdown.markdown 和 markdown.markdownFromFile 用于处理简短的 Markdown 内容，而复杂的内容可以使用 markdown.Markdown。

2.1 markdown.markdown(text [, **kwargs])

你可以直接读取：

with open("some_file.txt", "r", encoding="utf-8") as input_file:
    text = input_file.read()
html = markdown.markdown(text)

如果您想要写入 HTML，可以：

with open("some_file.html", "w", encoding="utf-8", errors="xmlcharrefreplace") as output_file:
    output_file.write(html)

2.1.1 extensions

Python-Markdown 提供了一个 API，供第三方将扩展写入解析器，添加其自己的添加或更改到语法。一些常用的扩展随标记库一起提供。有关可用扩展列表，请参阅 extension documentation。扩展列表可能包含扩展名和/或扩展名字符串的实例。

extensions=[MyExtClass(), 'myext', 'path.to.my.ext:MyExtClass']

注意：首选方法是传递扩展的实例。只有在无法直接导入扩展类（从命令行或模板中）时，才应使用字符串。

在传递扩展实例时，每个类实例必须是 markdown.extensions.Extension 扩展的子类，在启动类实例时应定义任何配置选项，而不是使用 extension_configs 关键字。例如：

from markdown.extensions import Extension
class MyExtClass(Extension):
    # define your extension here...

markdown.markdown(text, extensions=[MyExtClass(option='value')])

如果扩展名作为字符串提供，则字符串必须是任何已安装的扩展的注册入口点或使用 Python 的点符号的可导入路径。

请参阅特定于作为入口点分配给扩展的字符串名称的扩展的文档。只需在扩展列表中将定义的名称作为字符串包含。例如，如果扩展具有分配给它的名称 myext，并且扩展已正确安装，则执行以下操作：

markdown.markdown(text, extensions=['myext'])

如果扩展没有注册的入口点，则可以使用 Python 的点符号。扩展必须作为 Python 路径上的 Python 模块安装。通常，应在名称中指定类。类必须处于名称的末尾，并且由冒号从模块中分隔。

因此，如果要导入类，请进行以下操作：

from path.to.module import MyExtClass

然后加载扩展，如下所示：

markdown.markdown(text, extensions=['path.to.module:MyExtClass'])

如果在模块中只定义了一个扩展，并且模块包含一个 makeExtension 函数，该函数返回扩展的实例，则不需要类名称。例如，在这种情况下，可以执行扩展 extensions=['path.to.module']。检查文档以选择特定扩展，以确定它是否支持此功能。

按名称加载扩展名（作为字符串）时，只能通过使用"名称"关键字将配置设置传递给 extension_configs。

2.1.2 extension_configs

扩展的配置设置字典。

任何配置设置将仅传递到按名称（作为字符串）加载的扩展。将扩展加载为类实例时，在初始化时将配置设置直接传递给类。

Note: The preferred method is to pass in an instance of an extension, which does not require use of the extension_configs keyword at all. See the extensions keyword for details.

配置设置的字典必须采用以下格式：

extension_configs = {
    'extension_name_1': {
        'option_1': 'value_1',
        'option_2': 'value_2'
    },
    'extension_name_2': {
        'option_1': 'value_1'
    }
}

指定扩展名时，请确保使用与扩展关键字中使用的完全相同的字符串来加载扩展名。否则，配置设置将不应用于扩展。换句话说，您不能使用输入点就位和 Python 点符号在其他。虽然两者都对给定的扩展有效，但 Markdown 不会将它们识别为同一扩展。

有关指定该扩展的配置设置的帮助，请参阅特定于您使用的扩展的文档。

2.1.3 output_format

输出格式。

支持的格式包括：

• "xhtml"：输出 XHTML 样式标记。默认。
• "html5"：输出 HTML 样式标记。

这些值可以是小写或大写。

tab_length：源中的选项卡(tabs)长度。默认值： 4。

2.2 markdown.markdownFromFile (**kwargs)¶

除了少数例外，markdown.markdownFromFile 接受与 markdown.markdown 相同的选项。它不接受文本（或 Unicode）字符串。相反，它接受以下必需选项：

• input (required)：源文本文件。可以设置为三个选项之一：

  • 包含文件系统上可读文件的路径的字符串，
  • 一个可读的文件样对象，
  • 或 None（默认），它将从 stdin 读取。

• output：写入输出的目标。可以设置为三个选项之一：

  • 包含文件系统上可写文件的路径的字符串，
  • 一个可写文件样的对象，
  • 或 None（默认），这将写入 stdout。

• encoding：源文本文件的编码。

  • 默认值为"utf-8"。输入和输出将始终使用相同的编码。对输出进行编码时，使用 xmlcharrefreplace 错误处理程序。

Note: This is the only place that decoding and encoding of Unicode takes place in Python-Markdown. If this rather naive solution does not meet your specific needs, it is suggested that you write your own code to handle your encoding/decoding needs.

2.3 markdown.Markdown([**kwargs])¶

初始化 markdown.Markdown 时，相同的选项可用。markdown.Markdown 类在 markdown.markdown 函数上，只不过该类在初始化时不接受源文本字符串。相反，源文本字符串必须传递到两个实例方法之一。

Warning: Instances of the markdown.Markdown class are only thread safe within the thread they were created in. A single instance should not be accessed from multiple threads.

2.3.1 Markdown.convert(source)

source 文本必须满足与 text markdown.markdown 函数的参数（https：//python-markdown.github.io/参考/#markdown）相同要求。

如果要处理多个字符串而不为每个字符串创建类的新实例，则还应使用此方法。

md = markdown.Markdown()
html1 = md.convert(text1)
html2 = md.convert(text2)

根据正在使用的选项和/或扩展，解析器可能需要在每个调用之间重置其状态才能 convert。

html1 = md.convert(text1)
md.reset()
html2 = md.convert(text2)

为了便于此，您还可以链接调用以一起 reset：

html3 = md.reset().convert(text3)

2.3.2 Markdown.convertFile(**kwargs)

The arguments of this method are identical to the arguments of the same name on the markdown.markdownFromFile function (input, output, and encoding). As with the convert method, this method should be used to process multiple files without creating a new instance of the class for each document. State may need to be reset between each call to convertFile as is the case with convert.

3 在命令行使用 Python-Markdown

运行模块作为脚本提供的选项和参数。

python -m markdown [options] [args]

在最基本的用法中，只需将文件名作为唯一的参数传递：

python -m markdown input_file.txt

管道输入和输出（在STDIN和STDOUT上）也完全支持。例如：

echo "Some **Markdown** text." | python -m markdown > output.html

若要从命令行加载 Python 标记扩展，请使用 -x（或 --extension）选项。扩展模块必须放在 PYTHONPATH 上（有关详细信息，请参阅Extension API）。然后，可以通过分配给入口点的名称调用该扩展，或使用 Python 的点符号指向扩展

例如，若要加载具有分配的入口点名称 myext 的扩展，请运行以下命令：

python -m markdown -x myext input.txt

要加载使用 Python 的点表示法的扩展：

python -m markdown -x path.to.module:MyExtClass input.txt

要加载多个扩展，请为每个扩展指定一个 -x 选项：

python -m markdown -x myext -x path.to.module:MyExtClass input.txt

如果扩展支持配置选项（请参阅用于确定它支持的设置（如果有）的扩展的文档），您也可以将它们传递：

python -m markdown -x myext -c config.yml input.txt

-c（或 --extension_configs）选项接受文件名。该文件必须采用 YAML 或 JSON 格式，并包含 YAML 或 JSON 数据，这些数据将映射到 Python 字典，其格式为markdown.Markdown的 extension_configs 关键字所需的格式。\因此，上面示例中引用的文件 config.yaml 可能看起来像：

myext:
    option1: 'value1'
    option2: True

同样，JSON 配置文件可能看起来像：

{
  "myext":
  {
    "option1": "value1",
    "option2": "value2"
  }
}

请注意，虽然 --extension_configs 选项确实指定了 myext 扩展，但您仍然需要使用 -x 选项加载扩展，否则将忽略该扩展的配置。此外，如果扩展需要无法在 JSON 中解析的值（例如对函数的引用），则必须使用 YAML 配置文件。

--extension_configs 仅在您的系统上安装了 PyYAML 时才支持 YAML 配置文件。JSON 应无需使用其他依赖项。将自动检测配置文件的格式。

4 Writing Extensions for Python-Markdown

5 Test Tools

6 Contributing to Python-Markdown

7 Extensions

8 Third Party Extensions

9 代码高亮：google-prettify