作者选择了 COVID-19 Relief Fund 作为 Write for DOnations 计划的一部分来接受捐赠。
介绍
Markdown 是一种常用的标记语言，用于简化以易于阅读的文本格式编写内容的过程，软件工具或编程库可以将其转换为 HTML 以显示在浏览器或其他写作程序。 因为它使用纯文本语法，Markdown 与任何文本编辑器兼容，可以转换标题、列表、链接和其他组件。 博主、教程作者和文档作者广泛使用 Markdown，Github、StackOverflow 和 Python 包索引 (PyPI) 等网站都支持它。
您可以从 Markdown 语法 标准中学习如何使用 Markdown。 或者，您也可以在 Web 编辑器中尝试不同的 Markdown 实现，例如 DigitalOcean Markdown Preview 或 StackEdit 编辑器。
Python-Markdown 是一个 Python 库，可让您以各种方式将 Markdown 文本转换为 HTML。 您可以使用提供附加功能的不同 扩展 来扩展其功能。 但是请注意，Python-Markdown 与标准 Markdown 语法 有一些细微的 差异。
在本教程中，您将安装 Python-Markdown 库，使用它将 Markdown 字符串转换为 HTML，将 Markdown 文件转换为 HTML 文件，并使用 Python-Markdown 命令行界面将 Markdown 转换为 HTML。
先决条件
在开始遵循本指南之前，您需要：
- 本地 Python 3 编程环境。 按照 如何为 Python 3 系列安装和设置本地编程环境中的分发教程进行操作。 在本教程中，我们将调用我们的项目目录
pymark。 - 了解基本的 Python 和 HTML 概念，您可以查看我们的 如何在 Python 3 中编码 和 如何使用 HTML 构建网站教程系列以获取背景知识。
第 1 步 — 安装 Python-Markdown
在此步骤中，您将安装 Python-Markdown 并探索其功能之一，以在 Python REPL 中将 Markdown 字符串转换为 HTML。
如果您还没有激活您的编程环境，请确保您在您的项目目录中 (pymark) 并使用以下命令来激活环境：
source env/bin/activate
一旦你激活了你的编程环境，你的提示现在将有一个 env 前缀，如下所示：
现在您将安装 Python 包并将您的项目代码与主要的 Python 系统安装隔离开来。
通过运行以下命令，使用 pip 安装 Python-Markdown 库 (markdown)：
pip install markdown
安装成功完成后，您可以在 Python REPL 中进行试验，您可以通过键入以下命令打开它：
python
您会注意到一个带有前缀 >>> 的新提示； 您可以使用它来输入 Python 代码并立即接收输出。
首先，您将导入 markdown 包并使用它将一段 Markdown 文本从 Markdown 语法转换为 HTML：
import markdown
markdown.markdown('#Hi')
在此代码中，您导入了之前安装的 markdown 包。 您使用 markdown.markdown() 函数将 Markdown 文本 #Hi（其中 # 表示 H1 级别的标头）转换为其 HTML 等效项。 如果您将代码键入 Python REPL，您将收到以下输出：
Output'<h1>Hi</h1>'
HTML 输出相当于 #Hi Markdown 文本。
您可以使用三个单引号 () 在 Python REPL 中键入多行 Markdown 文本，如下所示：
import markdown
output = markdown.markdown('''
# Step 1
## Step 2
* item 1
* item 2
Visit [the tutorials page](https://www.digitalocean.com/community/tutorials) for more tutorials!
''')
print(output)
在此示例中，您传递了一个 H1 标题、一个 H2 标题、两个列表项和一个包含链接的段落。 然后将输出保存在一个名为 output 的变量中，并使用 print() Python 函数打印它。
您将收到以下输出：
Output<h1>Step 1</h1> <h2>Step 2</h2> <ul> <li>item 1</li> <li>item 2</li> </ul> <p>Visit <a href="https://www.digitalocean.com/community/tutorials">the tutorials page</a> for more tutorials!</p>
您会注意到输出结果是所提供 Markdown 文本的 HTML 版本。
现在您已经使用 markdown 包将 Markdown 文本转换为 HTML，您将编写一个小程序来读取 Markdown 文件并将其转换为 HTML 文件。
第 2 步 — 创建将 Markdown 文件转换为 HTML 的程序
在这一步中，您将创建一个 Python 程序来读取 Markdown 文件，使用 markdown.markdown() 函数将其内容转换为 HTML，并将 HTML 代码保存在新文件中。
首先，打开一个名为 Picnic.md 的新文件来保存 Markdown 文本：
nano Picnic.md
在其中输入以下 Markdown 文本：
pymark/Picnic.md
# Things to bring * Food. * Water. * Knife. * Plates.
在此文件中，您有一个 H1 标题和四个列表项。
完成后，保存并关闭文件。
接下来，打开一个名为 convert.py 的新文件，其中包含将 Picnic.md Markdown 文件转换为 HTML 文件的代码：
nano convert.py
在其中输入以下 Python 代码：
pymark/convert.py
import markdown
with open('Picnic.md', 'r') as f:
text = f.read()
html = markdown.markdown(text)
with open('Picnic.html', 'w') as f:
f.write(html)
在这里，您首先导入 markdown 包。 您使用 open() 函数打开 Picnic.md 文件； 将值 'r' 传递给 mode 参数以表示 Python 应该打开它进行读取。
您将文件对象保存在一个名为 f 的变量中，您可以使用它来引用该文件。 然后读取文件并将其内容保存在 text 变量中。 之后，您使用 markdown.markdown() 转换文本，将结果保存在名为 html 的变量中。
使用相同的模式，以写入模式 ('w') 打开一个名为 Picnic.html 的新文件——注意这个文件还不存在——然后写入 html 的内容文件的变量。 这会在您的系统上创建并保存新文件。 打开文件时使用 with 语句可确保 Python 在处理完成后将其关闭。
保存并关闭文件。
运行convert.py程序：
python convert.py
这将在您的项目目录中创建一个名为 Picnic.html 的新文件，其中包含以下内容：
pymark/Picnic.html
<h1>Things to bring</h1> <ul> <li>Food.</li> <li>Water.</li> <li>Knife.</li> <li>Plates.</li> </ul>
现在您知道如何使用 markdown.markdown() 函数打开和转换 Markdown 文件，您可以在 Python 中生成 Markdown 文本并转换 Markdown 文件，而无需先阅读它们。
第 3 步 — 从数据生成 Markdown 并将其转换为 HTML
在这一步中，您将创建一个程序，从 Python 字典 生成 Markdown 文本，将其保存到 Markdown 文件，并使用 markdown.markdownFromFile() 函数将 Markdown 文本转换为 HTML 文件。
您的程序将生成一个名为 cities.md 的 Markdown 文件，其中包含国家/地区及其前三个最大城市的列表。 之后，程序会将生成的 Markdown 文本转换为 HTML，然后将 HTML 保存在一个名为 cities.html 的文件中。
首先打开一个名为 citygen.py 的新 Python 文件：
nano citygen.py
然后添加以下 Python 代码：
pymark/citygen.py
import markdown
country_cities = {'Japan': ['Tokyo', 'Osaka', 'Nagoya'],
'France': ['Paris', 'Marseille', 'Lyon'],
'Germany': ['Berlin', 'Hamburg', 'Munich'],
}
在此代码中，您首先使用 import markdown 导入 Python-Markdown 库。 然后定义一个 country_cities 字典，其中包含几个国家作为键，每个国家最大的三个城市的 list 作为值。 这个字典是一个示例数据结构； 您可以将其替换为从 Web API、数据库或任何其他数据源获取的数据。
接下来在您的字典后添加以下代码：
pymark/citygen.py
. . .
with open('cities.md', 'bw+') as f:
for country, cities in country_cities.items():
f.write('# {}\n'.format(country).encode('utf-8'))
for city in cities:
f.write('* {}\n'.format(city).encode('utf-8'))
f.seek(0)
markdown.markdownFromFile(input=f, output='cities.html')
构建保存数据的字典后，使用 with open(...) as ... 语法 打开一个名为 cities.md 的文件，该文件尚不存在。 您以二进制模式 ('b') 打开它以进行写入和读取 ('w+')。 您使用二进制模式，因为如果将字符串传递给 markdown.markdownFromFile()，它将被解释为文件系统上可读文件的路径（即 '/home/file.md'）。 此外 二进制模式 允许您避免与将字符转换为特定于平台的表示相关的问题； 这保证了 Python 程序在任何平台上的行为方式都相同。
然后，您浏览字典的项目，提取包含国家名称的每个键并将其保存在 country 变量中。 除此之外，您提取代表该国最大城市列表的值并将其保存在 cities 变量中。
在第一个 循环 中，您将国家名称写入 # Markdown 标头（<h1> HTML 标记）中的新 cities.md 文件。 \n 是用于插入新行的特殊字符。 您使用 .encode() 是因为您已以二进制模式打开文件。 第二个 for 循环遍历每个城市并将其名称作为 * 列表项（<li> HTML 标记）写入 Markdown 文件。
第一个循环结束后，你已经移动到文件的末尾，这意味着 markdown.markdownFromFile() 将无法读取其内容； 因此，您使用 f.seek(0) 返回文件顶部。 在将 f 对象作为输入传递给 markdown.markdownFromFile() 之前，将其转换为 HTML 并将其保存到名为 cities.html 的新文件中。
完成后，保存并关闭文件。
运行citygen.py程序：
python citygen.py
此命令将生成两个文件：
cities.md：一个 Markdown 文件，内容如下：
pymark/cities.md
# Japan * Tokyo * Osaka * Nagoya # France * Paris * Marseille * Lyon # Germany * Berlin * Hamburg * Munich
cities.html：一个 HTML 文件，包含转换cities.md的内容的结果：
pymark/cities.html
<h1>Japan</h1> <ul> <li>Tokyo</li> <li>Osaka</li> <li>Nagoya</li> </ul> <h1>France</h1> <ul> <li>Paris</li> <li>Marseille</li> <li>Lyon</li> </ul> <h1>Germany</h1> <ul> <li>Berlin</li> <li>Hamburg</li> <li>Munich</li> </ul>
您还可以使用功能 markdown.markdownFromFile() 来转换现有的 Markdown 文件。 例如，您可以使用以下代码将 Picnic.md 文件转换为名为 Picnic-out.html 的文件：
例子.py
import markdown markdown.markdownFromFile(input='Picnic.md', output='Picnic-out.html')
如果文件不需要任何修改，可以使用markdown.markdownFromFile()函数直接转换文件。 如果您确实需要修改 Markdown 文件，您可以阅读它，然后使用 Step 2 中演示的方法进行转换。
您已经在 Python 代码中将 Markdown 文本转换为 HTML，但是 Python-Markdown 还提供了一个有用的命令行界面 (CLI) 以将 Markdown 文件快速转换为 HTML——您将在下一步中查看此工具。
第 4 步 — 使用 Python-Markdown 的命令行界面
在此步骤中，您将使用 Python-Markdown 的 CLI 将 Markdown 文件转换为 HTML 并打印输出，或将其保存为 HTML 文件。
您可以使用 Python 支持的 -m 标志运行 Python-Markdown 命令行脚本，它将库模块作为脚本运行。 例如，要转换 Markdown 文件，可以将其传递给 markdown 命令，如下所示，将 filename.md 替换为要转换的文件的名称：
python -m markdown filename.md
执行此命令将打印 filename.md 文件中存在的 Markdown 文本的 HTML 代码。
例如，要转换 Picnic.md 文件，请运行以下命令：
python -m markdown Picnic.md
这将打印以下输出：
Output<h1>Things to bring</h1> <ul> <li>Food.</li> <li>Water.</li> <li>Knife.</li> <li>Plates.</li> </ul>
要将输出保存到名为 output.html 的文件中，请使用以下命令：
python -m markdown Picnic.md -f output.html
有了这个，您现在已经使用 markdown 命令行界面将 Markdown 文件转换为 HTML。
结论
在本教程中，您使用 Python 将 Markdown 文本转换为 HTML。 您现在可以编写自己的 Python 程序，在不同的上下文中利用 Markdown 语法，例如使用 Flask 或 Django 等 Web 框架的 Web 应用程序。 有关如何使用 Python-Markdown 和 Flask 构建应用程序的教程，请阅读 如何使用 Python-Markdown 和 Flask 和 SQLite。
有关如何使用 Markdown 的更多信息，请查看 Markdown 网站。 有关在 Python 中使用 Markdown 的更多信息，请查看 Python-Markdown 文档。
以下是 Python-Markdown 官方支持的一些扩展：
- Extra：为标准 Markdown 语法添加额外功能的扩展，例如定义缩写、为各种 HTML 元素、脚注、表格和其他功能添加属性。
- CodeHilite：为代码块添加语法高亮的扩展。
- 目录：从 Markdown 文档生成目录并将其添加到生成的 HTML 文档中的扩展。
