在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
译者：阿布铥