在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文檔中的鏈接!現在，在不同環境之間移動文檔和保持內容整潔要容易多了，最重要的是，可以保持正確和最新!

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

題外話

本文中所描述的功能對我們很有用，但是你可能需要根據自己的需求對它進行調整。

如果你需要一些想法，那么除了這個擴展之外，我們還創建了一個markdown Preprocessor，它允許作者們在markdown中使用常量。例如，我們定義了一個名為SUPPORT_EMAIL的常量，我們像這樣使用它:

該預處理程序將用我們定義的文本替換字符串$SUPPORT_EMAIL，然后才渲染Markdown。

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

者 | 單雨

責編 | 胡巍巍

出品 | CSDN（ID：CSDNnews）

前言

為了實現模板封裝和復用，提高HTML界面調試便捷性以及前后端解耦等目標，Django定義了自己的網絡模板語言。

當前介紹模板語言的官方文檔已經非常完備，幾乎涵蓋了開發中需要用到的知識點和需要注意的問題，但同時官方文檔也存在一些問題：

翻譯不夠完善，帶來閱讀的困難；
一些知識點的介紹過于簡短，存在大量的頁內鏈接，閱讀時需要跳轉到不同的頁面，閱讀不連貫。

本文基于官方文檔系統介紹了Django模板語言的基礎知識點，方便快速了解Django模板語言。

模板系統設計哲學

Django的模板系統不是簡單的把Python嵌入到HTML中。

它的設計宗旨是：模板系統旨在展示內容, 而不是程序邏輯，因此不在HTML頁面中嵌入Python。

簡單的說，模板只負責渲染數據，大多數邏輯應該交給視圖（view）進行處理。

模板簡介

模板是一個簡單的文本文件。它可以生成任何基于文本的格式（如 HTML,XML,CSV等）。除了基本的HTML標簽外，模板還包含兩種額外的元素——變量和標簽。

模板中包含的變量可以被替換為變量的值，標簽則被替換為相應的模板控制邏輯。示例：

django
{% extends "base_generic.html" %}
{% block title %}{{ section.title }}{% endblock %}
{% block content %}
<h1>{{ section.title }}</h1>
{% for story in story_list %}
<h2>
<a href="{{ story.get_absolute_url }}">
{{ story.headline|upper }}
</a>
</h2>
<p>{{ story.tease|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}

`{{ section.title }}`在模板渲染時將會被變量的值替換，for標簽可以實現模板的循環渲染。

基礎語法

變量

變量實現從模板上下文字典（返回HTTP響應時傳遞過來的字典）中輸出一個值，這是一個類似于dict的對象，包含鍵值對。當模板引擎遇到一個變量時，它會計算該變量，并用結果替換它。

變量名由字母、數字字符和下劃線("_")組成，但不能以下劃線開頭。點(".")也出現在變量中，代表屬性調用，變量名中不能有空格或標點符號。

示例：

django
My first name is {{ first_name }}. My last name is {{ last_name }}.

當傳入一個上下文字典`{'first_name': 'John', 'last_name': 'Doe'}`時，將會渲染得到：

django

My first name is John. My last name is Doe.

模板中的變量被字典中的值替換了。

變量還可以使用點表示法實現字典查找、屬性查找和列表索引查找等操作：

django
{{ my_dict.key }}
{{ my_object.attribute }}
{{ my_list.0 }}

點表示法底層原理

當模板系統遇到一個點,它會按順序嘗試下面的動作：

1. 字典查詢

2. 屬性或方法查找

3. 數字索引查詢

如果結果值是可調用的，則調用該值時將不帶參數，調用的結果成為新的模板值。

當進行能覆蓋字典查找的操作時，這種查找順序可能會造成一些意想不到的行為。例如：如果試圖循環一個collection .defaultdict字典對象：

django
{% for k, v in defaultdict.items %}
{其他操作}
{% endfor %}

因為字典查找是首先發生的，所以這個行為會先提供一個默認值，而不是使用預期的.items方法。在這種情況下，應該首先考慮使用字典查找，而不是使用字典的屬性調用。

注意

屬性通常被解釋為一個文本字符串，防止和同名的變量沖突。例如{{foo.bar}}中的屬性“bar”將被解釋為一個文本字符串，如果模板上下文中存在變量“bar”，則不會使用該變量的值。

以下劃線開頭的變量屬性可能不能訪問，因為它們通常被認為是私有的。

如果引用不存在的變量，模板系統將插入string_if_invalid選項的值，該選項默認設置為“”(空字符串)。

標簽

標簽在模板渲染過程中提供任意邏輯。標簽可以輸出內容，作為控制結構，例如“if”語句或“for”循環，從數據庫獲取內容，甚至允許訪問其他模板標簽。

（1）標簽聲明

標簽的一般形式為：

django
{% tag %}

示例：

django
{% csrf_token %}

（2）傳入參數

django
{% cycle 'odd' 'even' %}

（3）成對使用的標簽

有些標簽需要開始和結束標簽：

django
{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}

（4）常用標簽

for：循環數組中的每個元素. 比如, 顯示列表 `athlete_list` 中每個元素的 `name` 屬性。

django
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
</ul>

if 、elif和else：在上面，如果athlete_list不為空，則{{athlete_list|length}}變量將顯示運動員的數量。

否則，如果athlete_in_locker_room_list不為空，則會顯示“Athletes should be out…”消息。如果兩個列表都為空，則顯示“No athletes”。

也可以在if標簽里使用過濾器和各種操作符：

django
{% if athlete_list|length > 1 %}
Team: {% for athlete in athlete_list %} ... {% endfor %}
{% else %}
Athlete: {{ athlete_list.0.name }}
{% endif %}

注意

雖然上面的示例可以工作，但是要注意，大多數模板過濾器都返回字符串，因此使用過濾器進行數學比較通常不會正常工作，而長度是個例外。

（5）更多

Django有很多內置標簽，更多關于內置標簽的信息請參考官方文檔：

https://docs.djangoproject.com/zh-hans/2.2/ref/templates/builtins/ref-templates-builtins-tags

如果需要編寫自定義標簽，請參考官方文檔

https://docs.djangoproject.com/zh-hans/2.2/howto/custom-template-tags/howto-writing-custom-template-tags

如果需要對使用的標簽和自定義的標簽做一份說明文檔，可以使用Django提供的文檔工具，詳情請參考：

https://docs.djangoproject.com/zh-hans/2.2/ref/contrib/admin/admindocs/

過濾器

簡介

過濾器可以對變量做一些操作，例如給變量賦值，改變變量的值等。

修改變量顯示

過濾器可以修改變量的顯示。例如：

django
{{ name|lower }}

通過過濾器lower變量{{ name }}變為了小寫字符，通過管道符(|)間隔變量和過濾器來使用過濾器。

鏈式調用過濾器

一個過濾器的輸出可以作為下一個過濾器的輸入。

{{ text|escape|linebreaks }}是一種常用的轉換方式, 在這之后換行符被替換為了 <p> 標簽。

轉換變量和標簽參數

過濾器轉換變量和標簽參數的值。示例：

django
{{ django|title }}

傳入`{'django': 'the web framework for perfecalist With deadline '}`上下文字典時，該模板呈現為：

django

The Web Framework For Perfectionists With Deadlines

傳入參數給過濾器

示例1：

django
{{ my_date|date:"Y-m-d" }}

my_date將會被替換為當前日期。

示例2：

django 
{{ bio|truncatewords:30 }}

將會會顯示 `bio` 變量的前30個字符

注意

過濾器參數中如果包含空格和標點符號，必須使用引號“”括起來，例如，要用逗號和空格連接列表，可以使用{{list|join:"， "}}。

Django提供了大約60個內置模板過濾器，請參考官方文檔：

https://docs.djangoproject.com/zh-hans/2.2/ref/templates/builtins/ref-templates-builtins-filters，

下面列舉一些常用的過濾器：

default

如果變量為false或空，則使用給定的默認值。否則，使用變量的值。例如：

django
{{ value|default:"nothing" }}

如果 `value` 沒有提供或者為空，那么將它顯示為 "`nothing`" 。

length

返回值的長度。這對字符串和列表都適用。例如：

django
{{ value|length }}

如果 `value` 為 `['a', 'b', 'c', 'd']`, 那么他將被顯示為 `4`。

filesizeformat

將值格式化為“人類可讀的”文件大小(即“13kb”、“4.1 MB”、“102字節”等)。例如：

django
{{ value|filesizeformat }}

如果值為123456789，則輸出為117.7 MB。

如果需要自定義過濾器，請參考請官方文檔：

https://docs.djangoproject.com/zh-hans/2.2/howto/custom-template-tags/

注釋

示例：

單行注釋

django
{ this won't be rendered }

多行注釋：{% comment %} 和{% endcomment %}

django
<p>Rendered text with {{ pub_date|date:"c" }}</p>
{% comment "Optional note" %}
<p>Commented out text with {{ create_date|date:"c" }}</p>
{% endcomment %}

注意：Comment標簽不能嵌套使用。

作者簡介：單雨，90后工科男，偽文藝青年。目前就讀于北京理工大學宇航系，喜歡研究AI，網絡爬蟲，微信小程序以及機器人，癡迷于Coding，睡前必擼碼。

【END】

兩天被django折磨的快崩潰了。要做一個網頁，結果CSS 和圖片總是加載不出來。官方文檔中教了一部分，上網看樂各種教程都不行，研究了好幾個小時，東拼西湊各個地方學一點，終于弄出來了，趕緊記錄下來。

django用的靜態文件路徑：STATICFILES_DIRS部署的方式，文件路徑一定要設置好。

注： python2.7 django1.10.6；項目mysite，項目下有一個應用myapp

一、目錄結構：

整個目錄結構是這樣的：

| mysite
| —— manage.py
| —— mysite
| —— | —— settings
| —— | ——…（urls等）
| —— templates
| —— myapp
| —— …(views等)
| —— | —— templates
| —— | —— | —— myapp
| —— | —— | —— | —— home.html
| —— | —— | —— | —— static
| —— | —— | —— | —— | —— css
| —— | —— | —— | —— | —— images

注意，文件夾結構比較復雜。

在項目文件夾下有一個templates文件夾，不過這個文件夾暫時沒什么用，可以不用管（我也不知道為什么要有這么個文件夾）。

應用文件夾結構是這樣的：

“myapp/templates/myapp/home.html”；
“myapp/templates/myapp/static/images”；
“myapp/templates/myapp/static/CSS”；

二、設置templates和靜態路徑

在settings.py中設置templates路徑

TEMPLATES = [

{

'BACKEND': 'django.template.backends.django.DjangoTemplates',

'DIRS': [os.path.join(BASE_DIR, 'myapp/templates').replace('\', '/'),

os.path.join(BASE_DIR, 'templates').replace('\', '/')],

}

]

1
2
3
4
5
6
7
在settings.py文件的最后加上以下內容：

STATIC_ROOT = os.path.join(BASE_DIR, 'myapp/templates/myapp/static').replace('\', '/')

STATICFILES_DIRS = (

('css', os.path.join(STATIC_ROOT, 'css').replace('\', '/')),

('images', os.path.join(STATIC_ROOT, 'images').replace('\', '/')),

)

三、修改urls.py文件

在urls.py開頭加上一句：

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

在urls.py的最后加上以下內容：

#設置靜態文件路徑

urlpatterns += staticfiles_urlpatterns()

四、修改html文件

home.html文件相關內容如下：

<!DOCTYPE html>

<head>

</head>

<body>

</a>

</body>

</html>

改成自己的圖片名稱，注意圖片和link的前綴：/static/images/ 別寫成 static/images/ ，這樣會無法顯示。

感覺自己底子真的太差，這幾天一點一點看官方文檔感到非常吃力，很多地方都不懂，想直接看自己需要的部分又不知道該看哪。

在線咨詢

上一篇：一篇文章讀懂微信小程序視圖層
下一篇：微信小程序常用的三種解析html方法，你了解多少

您的項目需求

*請認真填寫需求信息，我們會在24小時內與您取得聯系。

整合營銷服務商