轻松记录您
灵感和创意

在Django中使用Markdown

作为开发人员,我们依赖于静态分析工具来检查、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文档中的链接!现在,在不同环境之间移动文档和保持内容整洁要容易多了,最重要的是,可以保持正确和最新!

未经允许不得转载:坚果云Markdown编辑器 » 在Django中使用Markdown
分享到: 更多 (0)

坚果云Markdown轻松记录您 灵感和创意

坚果云Markdown下载坚果云Markdown介绍