为开发人员，我们依赖于静态分析工具来检查、lint(分析)和转换我们的代码。我们使用这些工具来帮助我们提高生产效率并生成更好的代码。然而，当我们使用markdown编写内容时，可用的工具就很少。

在本文中，我们将介绍如何开发一个Markdown扩展来解决在使用Markdown管理Django站点中的内容时遇到的挑战。

你认为他们有linter吗？

照片来自Pexels,由mali maeder拍摄

问题

像每个网站一样，我们在主页、FAQ部分和“关于”页面等地方都有不同类型的(大部分)静态内容。很长一段时间以来，我们都是在Django模板中直接管理这些内容的。

当我们最终决定是时候将这些内容从模板转移到数据库中时，我们认为最好使用Markdown。从Markdown生成HTML更安全，它提供了一定程度的控制和一致性，并且对于非技术用户来说更容易处理。随着我们转移过程的进展，我们注意到我们遗漏了一些东西:

内部链接

当URL更改时，链接到内部页面的链接可能会中断。在Django模板和视图中，我们使用了reverseand {% url %}，但是这在普通的Markdown中是不可用的。

在不同环境之间进行复制

绝对内部连接不能在不同环境之间进行复制。这可以使用相对链接来解决，不过目前没有开箱即用的增强这一点的方法。

无效链接

无效链接会损害用户体验，并导致用户质疑整个内容的可靠性。这并不是Markdown独有的东西，只不过HTML模板是由对URL有一定了解的开发人员维护的。另一方面，Markdown文档是为非技术写作人员设计的。

前期工作

当我研究这个问题时，我搜索了Python linters、Markdown预处理器和扩展来帮助生成更好的Markdown。结果都不是很好。一个引人注目的方法是使用Django模板来生成Markdown文档。

使用Django模板预处理Markdown

使用Django模板，你可以使用诸如url之类的模板标记来反向查询URL名称，并配合使用条件、变量、日期格式和所有其他Django模板特性。这种方法本质上是使用Django模板作为Markdown文档的预处理程序。

我个人认为这可能不是非技术作家的最佳解决方案。另外，我担心提供对Django模板标记的访问可能是危险的。

使用 Markdown

对这个问题有了更好的理解之后，我们准备在Python中更深入地研究Markdown。

将Markdown转换为HTML

要在Python中开始使用Markdown，我们先安装markdown包：

接着，创建一个Markdown对象并使用其函数将一些Markdown转换成HTML：

你现在可以在你的模板中使用这个HTML代码片段。

使用Markdown扩展

基本的Markdown处理器提供了生成HTML内容的基本要素。对于更“新奇”的选项，Python markdown包包含了一些内置扩展。一个流行的扩展是“extra”扩展，除了其他东西之外，它增加了对隔离代码块的支持:

为了使用我们独特的Django功能扩展Markdown，我们将开发自己的扩展。

创建一个Markdown扩展来处理内联链接

如果你查看源代码，你将看到要将markdown转换为HTML, Markdown会使用多种不同的处理器。一种类型的处理器是内联处理器。内联处理器会匹配特定的内联模式，如链接、反引号、粗体文本和带下划线的文本，并将它们转换为HTML。

我们的Markdown扩展的主要目的是验证和转换链接。因此，我们最感兴趣的内联处理器是LinkInlineProcessor。这个处理器以[Haki的网站](https://hakibenito.com)的形式获取markdown ，解析它并返回一个包含链接和文本的元组。

为了扩展该功能，我们扩展了LinkInlineProcessor并创建了一个Markdown.Extension, 我们用它来处理链接:

我们来将这段代码分解一下：:

• DjangoUrlExtension扩展注册了一个名为DjangoLinkInlineProcessor的内联链接处理器。这个处理器将取代任何其他现有的链接处理器。

• 内联处理器DjangoLinkInlineProcessor扩展了内置的LinkInlineProcessor，并在它处理的每个链接上调用clean_link函数。

• clean_link函数接收一个链接和一个域名，并返回一个转换后的链接。这就是我们要插入我们的实现的地方。

如何获得网站域名

要识别到你自己网站的链接，你必须知道你的网站的域名。如果你正在使用Django的sites框架，那么你可以使用它来获取当前域名。

我没有把它包含在我的实现中，因为我们没有使用sites框架。相反，我们在Django设置中设置了一个变量。

获取当前域名的另一种方法是使用HttpRequest对象。如果内容只在你自己的站点中被编辑，你可以尝试从请求对象中插入站点域名。这可能需要对你的实现进行一些更改。

要使用该扩展，请在初始化一个新的Markdown实例时添加它:

太好了，这个扩展已经被使用了，我们准备进入有趣的部分了！

验证和转换Django链接

既然我们得到了在所有链接上调用clean_link的扩展，那我们可以来实现我们的验证和转换逻辑。

验证mailto链接

要开始工作，我们将从一个简单的验证开始。mailto链接对于使用预定义的收件人地址、主题甚至消息正文打开用户的电子邮件客户端非常有用。

一个常见的mailto链接是这样的:

这个链接将打开你的电子邮件客户端，并设置成撰写一封主题行为“我需要帮助!”的新电子邮件给“support@service.com”。

mailto链接不一定非要包含电子邮件地址。如果你看一看这篇文章底部的“分享”按钮，你会发现像这样的一个mailto链接:

这个mailto链接没有包含收件人，仅包含了主题行和消息正文。

既然我们已经很好地理解了mailto链接是什么样子的，我们就可以向clean_link函数添加第一个验证:

为了验证mailto链接，我们向clean_link中添加了以下代码:

• 检查链接是否以mailto:开头，以识别相关链接。

• 使用正则表达式将链接分割到它的组件。

• 从mailto链接中删除实际的电子邮件地址，并使用Django的EmailValidator验证它。

注意，我们还添加了一种名为InvalidMarkdown的新异常类型。我们定义了自己的自定义异常类型，以将它与markdown本身所引发的其他错误区分开来。

自定义错误类

我曾经写过关于自定义错误类的文章，为什么它们是有用的，以及你什么时候应该使用它们。

在我们继续之前，让我们添加一些测试，看看它的实际效果:

太棒了！按预期的运行了。

处理内部和外部链接

既然我们已经了解了mailto链接，我们也可以处理其他类型的链接:

外部链接

• 我们的Django应用程序外部的链接。

• 必须包含一个页面跳转协议（scheme）:http或https。

• 理想情况下，我们还希望确保这些链接没有被破坏，但我们现在不会这样做。

内部链接

• 到我们的Django应用程序中的页面的链接。

• 链接必须是相对的:这将允许我们在不同环境之间移动内容。

• 使用Django的URL名称而不是一个URL路径:这将允许我们安全地来回移动视图，而不必担心markdown内容中的失效链接。

• 链接可能包含查询参数(?)和片段(#)。

SEO

从SEO的角度来看，公共URL不应该改变。当他们这样做的时候，你应该使用重定向正确地处理它，否则你可能会受到搜索引擎的惩罚。

有了这个需求列表，我们就可以开始工作了。

解析URL名称

要链接到内部页面，我们希望编写者提供一个URL名称，而不是URL路径。例如，假设我们有这个视图:

这个页面的URL路径是https://example.com/， URL名称是home。我们想要在我们的markdown链接中使用这个URL名称home，就像这样:

这将渲染到:

我们还想支持查询参数和散列：

这将渲染到以下HTML：

在使用URL名称时，如果我们更改了URL路径，内容中的链接将不会被破坏。要检查作者提供的href是否是一个有效的url_name，我们可以尝试reverse它:

URL名称“home”指向URL路径“/”。当没有匹配项时，将会引发一个异常:

在我们继续之前，当URL名称包含查询参数或散列时，会发生什么:

这是有意义的，因为查询参数和散列不是URL名称的一部分。

要使用reverse并支持查询参数和散列，我们首先需要清除值。然后，检查它是一个有效的URL名称，并返回包含查询参数和散列的URL路径，如果提供了的话:

这个代码段使用一个正则表达式来以？或#的出现对href进行分割，并返回各部分。

请确保它可以工作:

太了不起了!作者们现在可以在Markdown中使用URL名称了。它们还可以包括要添加到该URL的查询参数和片段。

处理外部链接

要正确处理外部链接，我们需要检查两件事:

1.外部链接总是提供一个跳转协议，http:或者https:。

2.阻止到我们自己网站的绝对链接。内部链接应该使用URL名称。

到目前为止，我们已经处理了URL名称和mailto链接。如果我们通过了这两个检查，这意味着href是一个URL。让我们从检查链接是否是链接到我们自己的网站开始:

函数urlparse会返回一个命名元组，该元组包含URL的不同部分。如果netloc属性等于site_domain，那么该链接就确实是一个内部链接。

如果URL实际上是内部的，我们就需要终止。但是，请记住，作者们不一定是技术人员，因此我们希望帮助他们，并提供一个有用的错误消息。我们要求该内部链接使用URL名称而不是URL路径，所以最好让作者们知道他们提供的路径的URL名称。

要获得一个URL路径的URL名称，Django为我们提供了一个名为resolve的函数:

当找到匹配项时，resolve会返回一个ResolverMatch对象，其中包含URL名称和其他信息。当没有找到匹配项时，它就会引发一个错误:

这实际上就是Django在底层所做的工作，用来确定在一个新请求到来时执行哪个视图函数。

为了给作者们提供更好的错误信息，我们可以使用来自ResolverMatch对象的URL名称:

当我们识别出内部链接时，我们要处理两种情况:

• 我们没有识别出这个URL:这个URL很可能是不正确的。请作者检查该URL是否有错误。

• 我们识别出了这个URL: 这个URL是正确的，所以就告诉作者应该使用什么URL名称。

我们来实际地看一下它:

漂亮!外部链接被接受，内部链接被拒绝，并带有一个有用的消息。

要求跳转协议

我们要做的最后一件事是确保外部链接包含一个跳转协议，要么是http:，要么是https:。让我们将这最后一部分添加到函数clean_link:

使用解析后的URL，我们可以很容易地检查跳转协议。让我们确保它正在工作:

我们向这个函数提供了一个没有跳转协议的链接，但是它运行失败了，并显示了一条有用的消息。太酷了!

整合代码

这是clean_link函数的全部代码：

要了解所有这些特性的一个实际用例是什么样子的，请看下面的内容:

这将产生以下HTML:

不错!

结论

我们现在有一个很不错的扩展，它可以验证和转换Markdown文档中的链接!现在，在不同环境之间移动文档和保持内容整洁要容易多了，最重要的是，可以保持正确和最新!

源码

你可以在这个gist中找到全部源代码。（地址：https://gist.github.com/hakib/73fccc340e855bb65f42197e298c0c7d ）

题外话

本文中所描述的功能对我们很有用，但是你可能需要根据自己的需求对它进行调整。

如果你需要一些想法，那么除了这个扩展之外，我们还创建了一个markdown Preprocessor，它允许作者们在markdown中使用常量。例如，我们定义了一个名为SUPPORT_EMAIL的常量，我们像这样使用它:

该预处理程序将用我们定义的文本替换字符串$SUPPORT_EMAIL，然后才渲染Markdown。

英文原文：https://hakibenita.com/django-markdown
译者：Nothing

markdown中写下你的文章，并使用Python将它们转换成HTML-作者Florian Dahlitz，于2020年5月18日（15分钟）

介绍

几个月前，我想开通自己的博客，而不是使用像Medium这样的网站。这是一个非常基础的博客，所有的文章都是HTML形式的。然而，有一天，我突然产生了自己编写Markdown到HTML生成器的想法，最终这将允许我用markdown来编写文章。此外，为它添加诸如估计阅读时间之类的扩展特性会更容易。长话短说，我实现了自己的markdown到HTML生成器，我真的很喜欢它！

在本系列文章中，我想向您展示如何构建自己的markdown到HTML生成器。该系列由三部分组成：

• 第一部分（本文）介绍了整个管线的实现。

• 第二部分通过一个模块扩展了实现的管线，该模块用于计算给定文章的预计阅读时间。

• 第三部分演示如何使用管线生成自己的RSS摘要。

这三部分中使用的代码都可以在GitHub上找到。

备注：我的文章中markdown到HTML生成器的想法基于Anthony Shaw文章中的实现。

项目构建

为了遵循本文的内容，您需要安装几个软件包。我们把它们放进requirements.txt文件。

Markdown是一个包，它允许您将markdown代码转换为HTML。之后我们用Flask产生静态文件。

但在安装之前，请创建一个虚拟环境，以避免Python安装出现问题：

激活后，您可以使用pip安装requirements.txt中的依赖。

很好！让我们创建几个目录来更好地组织代码。首先，我们创建一个app目录。此目录包含我们提供博客服务的Flask应用程序。所有后续目录都将在app目录内创建。其次，我们创建一个名为posts的目录。此目录包含要转换为HTML文件的markdown文件。接下来，我们创建一个templates目录，其中包含稍后使用Flask展示的模板。在templates目录中，我们再创建两个目录：

posts包含生成的HTML文件，这些文件与应用程序根目录中posts目录中的文件相对应。

shared包含在多个文件中使用的HTML文件。

此外，我们还创建了一个名为services的目录。该目录将包含我们在Flask应用程序中使用的模块，或者为它生成某些东西。最后，创建一个名为static的目录带有两个子目录images和css。自定义CSS文件和文章的缩略图将存储在此处。

您的最终项目结构应如下所示：

令人惊叹！我们完成了一般的项目设置。我们来看看Flask的设置。

Flask设置

路由

我们在上一节安装了Flask。但是，我们仍然需要一个Python文件来定义用户可以访问的端点。在app目录中创建main.py并将以下内容复制到其中。

该文件定义了一个具有两个端点的基础版Flask应用程序。用户可以使用/route访问第一个端点返回索引页，其中列出了所有文章。

第二个端点是更通用的端点。它接受post的名称并返回相应的HTML文件。

接下来，我们通过向app目录中添加一个__init__.py，将其转换为一个Python包。此文件为空。如果您使用UNIX计算机，则可以从项目的根目录运行以下命令：

模板

现在，我们创建两个模板文件index.html以及layout.html，都存储在templates/shared目录中。这个layout.html模板将用于单个博客条目，而index.html模板用于生成索引页，从中我们可以访问每个帖子。让我们从index.html模板开始。

它是一个基本的HTML文件，其中有两个元标记、一个标题和两个样式表。注意，我们使用一个远程样式表和一个本地样式表。远程样式表用于启用Bootstrap[1]类。第二个是自定义样式。我们晚点再定义它们。

HTML文件的主体包含一个容器，其中包含Jinja2[2]逻辑，用于为每个post生成Bootstrap卡片[3]。您是否注意到我们不直接基于变量名访问这些值，而是需要将[0]添加到其中？这是因为文章中解析的元数据是列表。实际上，每个元数据元素都是由单一元素组成的列表。我们稍后再看。到目前为止，还不错。让我们看看layout.html模板。

如你所见，它比前一个短一点，简单一点。文件头与index.html文件很相似，除了我们有不同的标题。当然，我们可以共用一个模板，但是我不想让事情变得更复杂。

body中的容器仅定义一个h1标记。然后，我们提供给模板的内容被插入并呈现。

样式

正如上一节所承诺的，我们将查看自定义CSS文件style.css. 我们在static/css中找到该文件，并根据需要自定义页面。下面是我们将用于基础示例的内容：

我不喜欢Bootstrap中blockquotes的默认外观，所以我们在左侧添加了一点间距和边框。此外，blockquote段落底部的页边空白将被删除。不删除的话看起来很不自然。

最后但并非最不重要的是，左右两边的填充被删除。由于两边都有额外的填充，缩略图没有正确对齐，所以在这里删除它们。

到现在为止，一直都还不错。我们完成了关于Flask的所有工作。让我们开始写一些帖子吧！

写文章

正如标题所承诺的，你可以用markdown写文章-是的！在写文章的时候，除了保证正确的markdown格式外，没有其他需要注意的事情。

在完成本文之后，我们需要在文章中添加一些元数据。此元数据添加在文章之前，并由三个破折号分隔开来---。下面是一个示例文章（post1.md）的摘录：

注意：您可以在GitHub库的app/posts/post1.md中找到完整的示例文章。

在我们的例子中，元数据由标题、副标题、类别、发布日期和index.html中卡片对应缩略图的路径组成.

我们在HTML文件中使用了元数据，你还记得吗？元数据规范必须是有效的YAML。示例形式是键后面跟着一个冒号和值。最后，冒号后面的值是列表中的第一个也是唯一的元素。这就是我们通过模板中的索引运算符访问这些值的原因。

假设我们写完了文章。在我们可以开始转换之前，还有一件事要做：我们需要为我们的帖子生成缩略图！为了让事情更简单，只需从你的电脑或网络上随机选取一张图片，命名它为placeholder.jpg并把它放到static/images目录中。GitHub存储库中两篇文章的元数据包含一个代表图像的键值对，值是placeholder.jpg。

注意：在GitHub存储库中，您可以找到我提到的两篇示例文章。

markdown到HTML转换器

最后，我们可以开始实现markdown to HTML转换器。因此，我们使用我们在开始时安装的第三方包Markdown。我们先创建一个新模块，转换服务将在其中运行。因此，我们在service目录中创建了converter.py。我们一步一步看完整个脚本。您可以在GitHub存储库中一次查看整个脚本。

首先，我们导入所需的所有内容并创建几个常量：

ROOT指向我们项目的根。因此，它是包含app的目录。

POSTS_DIR是以markdown编写的文章的路径。

TEMPLATE_DIR分别指向对应的templates目录。

BLOG_TEMPLATE_文件存储layout.html的路径。

INDEX_TEMPLATE_FILE是index.html

BASE_URL是我们项目的默认地址，例如。https://florian-dahlitz.de.默认值（如果不是通过环境变量DOMAIN提供的话）是http://0.0.0.0：5000。

接下来，我们创建一个名为generate_entries的新函数。这是我们定义的唯一一个转换文章的函数。

在函数中，我们首先获取POSTS_DIR目录中所有markdown文件的路径。pathlib的awesome glob函数帮助我们实现它。

此外，我们定义了Markdown包需要使用的扩展。默认情况下，本文中使用的所有扩展都随它的安装一起提供。

注意：您可以在文档[4]中找到有关扩展的更多信息。

此外，我们实例化了一个新的文件加载程序，并创建了一个在转换项目时使用的环境。随后，将创建一个名为all_posts的空列表。此列表将包含我们处理后的所有帖子。现在，我们进入for循环并遍历POSTS_DIR中找到的所有文章。

我们启动for循环，并打印当前正在处理的post的路径。如果有什么东西出问题了，这尤其有用。然后我们就知道，哪个文章的转换失败了。

接下来，我们在默认url之后增加一部分。假设我们有一篇标题为“面向初学者的Python”的文章。我们将文章存储在一个名为python-for-beginners.md,的文件中，因此生成的url将是http://0.0.0.0:5000/posts/python-for-beginners。

变量url_html存储的字符串与url相同，只是我们在末尾添加了.html。我们使用此变量定义另一个称为target_file.的变量。变量指向存储相应HTML文件的位置。

最后，我们定义了一个变量md，它表示markdown.Markdown的实例，用于将markdown代码转换为HTML。您可能会问自己，为什么我们没有在for循环之前实例化这个实例，而是在内部实例化。当然，对于我们这里的小例子来说，这没有什么区别（只是执行时间稍微短一点）。但是，如果使用诸如脚注之类的扩展来使用脚注，则需要为每个帖子实例化一个新实例，因为脚注添加后就不会从此实例中删除。因此，如果您的第一篇文章使用了一些脚注，那么即使您没有明确定义它们，所有其他文章也将具有相同的脚注。

让我们转到for循环中的第一个with代码块。

实际上，with代码块打开当前post并将其内容读入变量content。之后调用_md.convert将以markdown方式写入的内容转换为HTML。随后，env环境根据提供的模板BLOG_TEMPLATE_FILE（即layout.html如果你还记得的话）渲染生成的HTML。

第二个with 代码块用于将第一个with 代码块中创建的文档写入目标文件。

以下三行代码从元数据中获取发布日期（被发布的日期），将其转换为正确的格式（RFC 2822），并将其分配回文章的元数据。此外，生成的post_dict被添加到all_posts列表中。

我们现在出了for循环，因此，我们遍历了posts目录中找到的所有posts并对其进行了处理。让我们看看generate_entries函数中剩下的三行代码。

我们按日期倒序对文章进行排序，所以首先显示最新的文章。随后，我们将文章写到模板目录一个新创建的index.html文件中。别把index.html错认为templates/shared目录中的那个。templates/shared目录中的是模板，这个是我们要使用Flask服务的生成的。

最后我们在函数generate_entries之后添加以下if语句。

这意味着如果我们通过命令行执行文件，它将调用generate_entries函数。

太棒了，我们完成了converter.py脚本！让我们从项目的根目录运行以下命令来尝试：

您应该看到一些正在转换的文件的路径。假设您编写了两篇文章或使用了GitHub存储库中的两篇文章，那么您应该在templates目录中找到三个新创建的文件。首先是index.html，它直接位于templates目录中，其次是templates/posts目录中的两个HTML文件，它们对应于markdown文件。

最后启动Flask应用程序并转到http://0.0.0.0:5000。

总结

太棒了，你完成了这个系列的第一部分！在本文中，您已经学习了如何利用Markdown包创建自己的Markdown to HTML生成器。您实现了整个管线，它是高度可扩展的，您将在接下来的文章中看到这一点。

希望你喜欢这篇文章。一定要和你的朋友和同事分享。如果你还没有，考虑在Twitter上关注我@DahlitzF或者订阅我的通知，这样你就不会错过任何即将发表的文章。保持好奇心，不断编码！

参考文献

Bootstrap （http://getbootstrap.com/）

Primer on Jinja Templating （https://realpython.com/primer-on-jinja-templating/）

Bootstrap Card （https://getbootstrap.com/docs/4.4/components/card/）

Python-Markdown Extensions （https://python-markdown.github.io/extensions/）

Tweet

英文原文：https://florian-dahlitz.de/blog/build-a-markdown-to-html-conversion-pipeline-using-python
译者：阿布铥