如何使用 Python-Markdown 将 Markdown 文本转换为 HTML

作者选择了 COVID-19 救援基金作为 Write for Donations计划的一部分接受捐款。

介绍

Markdown是一种标记语言,通常用于简化易于阅读的文本格式中写内容的过程,软件工具或编程库可以将其转换为 HTML以在浏览器或其他写作程序中显示,因为它使用纯文本语法,所以 Markdown 与任何文本编辑器兼容,可以转换标题,列表,链接和其他组件。博客,教程作者和文档作者广泛使用标记和网站,如 Github, StackOverflow,和 Python Package Index (PyPI),支持它。

您可以从 Markdown 语法标准学习如何使用 Markdown. 或者,您也可以尝试在 Web 编辑器中使用不同的 Markdown 实现,例如 DigitalOcean Markdown Preview或 StackEdit编辑器。

Python-Markdown是一个Python库,允许您以各种方式将Markdown文本转换为HTML。您可以使用其不同的扩展(https://python-markdown.github.io/extensions/)来扩展其功能,这些扩展提供了额外的功能。

在本教程中,您将安装 Python-Markdown库,使用它将Markdown字符串转换为HTML,将Markdown文件转换为HTML文件,并使用Python-Markdown命令行界面将Markdown转换为HTML。

前提条件

在你开始遵循这个指南之前,你将需要:

一个本地的Python 3编程环境. 遵循如何安装和设置Python 3的本地编程环境系列(https://www.digitalocean.com/community/tutorial_series/how-to-install-and-set-up-a-local-programming-environment-for-python-3)的分布的教程。在本教程中,我们将把我们的项目目录称为pymark。
对基本的Python和HTML概念的理解,您可以查看我们的如何在Python中编码 3和如何使用HTML构建网站教程系列以获得背景知识。

步骤 1 – 安装 Python-Markdown

在此步骤中,您将安装Python-Markdown并探索其其中一个函数,以在Python REPL(https://andsky.com/tech/tutorials/how-to-work-with-the-python-interactive-console)中将Markdown字符串转换为HTML。

如果您尚未激活您的编程环境,请确保您位于项目目录中(‘pymark’),并使用以下命令激活环境:

1source env/bin/activate

一旦你激活了你的编程环境,你的提示将现在有一个env前缀,如下:

现在您将安装 Python 包,并将项目代码从主要的 Python 系统安装中分离出来。

使用pip来安装 Python-Markdown 库(标记),运行以下命令:

1pip install markdown

一旦安装顺利完成,您可以在Python REPL中试验它,您可以通过键入以下命令来打开它:

1python

你会注意到一个新的提示,前缀是>>>;你可以使用这个键入Python代码并获得即时输出。

首先,您将导入标记包,并使用它将Markdown文本从Markdown语法转换为HTML:

1import markdown
2markdown.markdown('#Hi')

在此代码中,您将导入您之前安装的标记包. 您使用标记函数将标记文本#Hi(与#代表H1级标题)转换为其HTML等级。

1[secondary_label Output]
2'<h1>Hi</h1>'

HTML 输出相当于 #Hi Markdown 文本。

您可以使用三重单引文(''')将多行标记文本输入Python REPL,如下:

 1import markdown
 2output = markdown.markdown('''
 3# Step 1
 4## Step 2
 5* item 1
 6* item 2
 7
 8Visit [the tutorials page](https://andsky.com/tech/tutorials) for more tutorials!
 9''')
10
11print(output)

在本示例中,您将一个H1标题、一个H2标题、两个列表项目和一个包含链接的段落传输,然后将输出存储在名为输出的变量中,并使用Python函数print()打印。

您将获得以下输出:

1[secondary_label Output]
2<h1>Step 1</h1>
3<h2>Step 2</h2>
4<ul>
5<li>item 1</li>
6<li>item 2</li>
7</ul>
8<p>Visit <a href="https://andsky.com/tech/tutorials">the tutorials page</a> for more tutorials!</p>

您会注意到输出结果是提供的 Markdown 文本的 HTML 版本。

现在你已经使用了标记包将标记文本转换为HTML,你将创建一个小程序来读取和转换标记文件为HTML文件。

步骤 2 — 创建一个程序将标记文件转换为HTML

在此步骤中,您将创建一个 Python 程序,该程序会读取 Markdown 文件,使用 markdown.markdown() 函数将其内容转换为 HTML,并将 HTML 代码保存到新文件中。

首先,打开一个名为Picnic.md的新文件,以保持 Markdown 文本:

1nano Picnic.md

输入以下 Markdown 文本:

1[label pymark/Picnic.md]
2# Things to bring
3
4* Food.
5* Water.
6* Knife.
7* Plates.

在这个文件中,你有一个H1标题和四个列表项目。

一旦完成,保存并关闭文件。

接下来,打开一个名为 'convert.py' 的新文件,以保持将 'Picnic.md' Markdown 文件转换为 HTML 文件的代码:

1nano convert.py

输入以下Python代码:

1[label pymark/convert.py]
2import markdown
3
4with open('Picnic.md', 'r') as f:
5    text = f.read()
6    html = markdown.markdown(text)
7
8with open('Picnic.html', 'w') as f:
9    f.write(html)

在这里,您首先导入标记包. 您使用 open()函数打开Picnic.md文件;将值'r传递到模式参数,表示Python应该打开它来读。

您将文件对象保存为名为f的变量,您可以使用该变量来参考该文件,然后您会读取该文件并将其内容保存在text变量中。

使用相同的模式,你在写模式中打开一个名为Picnic.html的新文件(w) - 注意这个文件尚不存在 - 并将html变量的内容写入到文件中。

保存并关闭文件。

运行convert.py程序:

1python convert.py

这会在项目目录中创建一个名为Picnic.html的新文件,其中包含以下内容:

1[label pymark/Picnic.html]
2<h1>Things to bring</h1>
3<ul>
4<li>Food.</li>
5<li>Water.</li>
6<li>Knife.</li>
7<li>Plates.</li>
8</ul>

现在你知道如何使用markdown.markdown()函数打开和转换Markdown文件,你可以在Python中生成Markdown文本并转换Markdown文件,而无需先阅读它们。

步骤 3 – 从数据中生成标记并将其转换为HTML

在此步骤中,您将创建一个程序,从 Python 字典生成 Markdown 文本,将其保存为 Markdown 文件,并使用 markdown.markdownFromFile() 函数将 Markdown 文本转换为 HTML 文件。

你的程序会生成一个名为cities.md的 Markdown 文件,其中列出了国家及其前三大城市,然后将生成的 Markdown 文本转换为 HTML,然后将 HTML 保存到名为cities.html的文件中。

首先打开一个名为citygen.py的新Python文件:

1nano citygen.py

然后添加以下Python代码:

1[label pymark/citygen.py]
2import markdown
3
4country_cities = {'Japan': ['Tokyo', 'Osaka', 'Nagoya'],
5                  'France': ['Paris', 'Marseille', 'Lyon'],
6                  'Germany': ['Berlin', 'Hamburg', 'Munich'],
7                  }

在这个代码中,你首先导入了Python-Markdown库的导入标记。然后,你定义了一个country_cities字典,其中包含几个国家作为密钥,以及每个国家最大的三个城市的列表作为值。

然后在你的字典后添加以下代码:

1[label pymark/citygen.py]
2. . .
3with open('cities.md', 'bw+') as f:
4    for country, cities in country_cities.items():
5        f.write('# {}\n'.format(country).encode('utf-8'))
6        for city in cities:
7            f.write('* {}\n'.format(city).encode('utf-8'))
8    f.seek(0)
9    markdown.markdownFromFile(input=f, output='cities.html')

在构建包含数据的字典后,你会使用以开放(...)为... 语法来打开一个名为cities.md的文件,它还不存在,你会以二进制模式('b')打开它来写和阅读('w+')。你会使用二进制模式,因为如果你将一个字符串传送到markdown.markdownFromFile(),它将被解释为文件系统上的可读文件的路径(即/home/file.md`)。

然后你通过字典的项目提取每个含有国家名称的密钥,并将其保存在国家变量中。

在第一个 loop中,你将国家的名称写入新的 cities.md 文件中,在一个 # Markdown 标题中(即 <h1> HTML 标签)。 \n 是插入新行的一种特殊字符.你使用 .encode() 是因为你在二进制模式下打开了该文件。

在第一个循环结束后,你已经移动到文件的尽头,这意味着markdown.markdownFromFile()将无法读取其内容;因此,你使用f.seek(0)回到文件的顶部。

一旦完成,保存并关闭文件。

运行citygen.py程序:

1python citygen.py

此命令将生成两个文件:

cities.md:包含以下内容的 Markdown 文件:

 1[label pymark/cities.md]
 2# Japan
 3* Tokyo
 4* Osaka
 5* Nagoya
 6# France
 7* Paris
 8* Marseille
 9* Lyon
10# Germany
11* Berlin
12* Hamburg
13* Munich

cities.html:包含对 `cities.md 的内容转换结果的 HTML 文件:

 1[label pymark/cities.html]
 2<h1>Japan</h1>
 3<ul>
 4<li>Tokyo</li>
 5<li>Osaka</li>
 6<li>Nagoya</li>
 7</ul>
 8<h1>France</h1>
 9<ul>
10<li>Paris</li>
11<li>Marseille</li>
12<li>Lyon</li>
13</ul>
14<h1>Germany</h1>
15<ul>
16<li>Berlin</li>
17<li>Hamburg</li>
18<li>Munich</li>
19</ul>

您还可以使用函数 markdown.markdownFromFile() 转换现有 Markdown 文件,例如,您可以使用以下代码将 Picnic.md 文件转换为名为 `Picnic-out.html' 的文件:

1[label example.py]
2import markdown
3
4markdown.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:

1python -m markdown filename.md

執行此命令會打印「filename.md」檔案中存在的 Markdown 文本的 HTML 代碼。

例如,要转换Picnic.md文件,请执行以下命令:

1python -m markdown Picnic.md

这将打印以下输出:

1[secondary_label Output]
2<h1>Things to bring</h1>
3<ul>
4<li>Food.</li>
5<li>Water.</li>
6<li>Knife.</li>
7<li>Plates.</li>
8</ul>

若要将输出保存到名为output.html的文件中,请使用以下命令:

1python -m markdown Picnic.md -f output.html

有了这个,你现在已经使用了标记命令行界面将Markdown文件转换为HTML。

结论

在本教程中,您已经使用了Python将Markdown文本转换为HTML,现在您可以编写自己的Python程序,在不同的环境中利用Markdown语法,例如使用Web框架的Web应用程序,如 Flask或 Django.有关如何使用Python-Markdown和Flask构建应用程序的教程,请阅读如何使用Python-Markdown与Flask和SQLite。

有关如何使用 Markdown 的更多信息,请参阅 Markdown 网站。有关如何使用 Markdown 与 Python 的更多信息,请参阅 Python-Markdown 文档。

以下是Python-Markdown官方支持的几个扩展:

Extra:为标准标记语法添加额外的功能的扩展,例如定义缩写,向各种 HTML 元素、脚注、表格和其他功能添加属性。
CodeHilite:一个扩展将语法突出添加到代码块中。