9 - 支持 Markdown 語法和代碼高亮

爲了讓博客文章具備良好的排版，顯示更加豐富的格式，咱們使用 Markdown 語法來書寫咱們的博文。Markdown 是一種 HTML 文本標記語言，只要遵循它約定的語法格式，Markdown 的渲染器就可以把咱們寫的文章轉換爲標準的 HTML 文檔，從而讓咱們的文章呈現更加豐富的格式，例如標題、列表、代碼塊等等 HTML 元素。因爲 Markdown 語法簡單直觀，不用超過 5 分鐘就能夠掌握經常使用的標記語法，所以你們青睞使用 Markdown 書寫 HTML 文檔。下面讓咱們的博客也支持使用 Markdown 書寫。

安裝 Python Markdown

將 Markdown 格式的文本渲染成標準的 HTML 文檔是一個複雜的工做，好在已有好心人幫咱們完成了這些工做，咱們直接使用便可。首先安裝 Markdown，這是一個 Python 第三方庫，激活虛擬環境，而後使用命令 pip install markdown 安裝便可。

在 detail 視圖中渲染 Markdown

將 Markdown 格式的文本渲染成 HTML 文本很是簡單，只需調用這個庫的 markdown 方法便可。咱們書寫的博客文章內容存在 Post 的 body 屬性裏，回到咱們的詳情頁視圖函數，對 post 的 body 的值作一下渲染，把 Markdown 文本轉爲 HTML 文本再傳遞給模板：

blog/views.py

import markdown
from django.shortcuts import render, get_object_or_404
from .models import Post

def detail(request, pk):
    post = get_object_or_404(Post, pk=pk)
    # 記得在頂部引入 markdown 模塊
    post.body = markdown.markdown(post.body,
                                  extensions=[
                                     'markdown.extensions.extra',
                                     'markdown.extensions.codehilite',
                                     'markdown.extensions.toc',
                                  ])
    return render(request, 'blog/detail.html', context={'post': post})複製代碼

這樣咱們在模板中展現 {{ post.body }} 的時候，就再也不是原始的 Markdown 文本了，而是渲染事後的 HTML 文本。注意這裏咱們給 markdown 渲染函數傳遞了額外的參數 extensions，它是對 Markdown 語法的拓展，這裏咱們使用了三個拓展，分別是 extra、codehilite、toc。extra 自己包含不少拓展，而 codehilite 是語法高亮拓展，這爲咱們後面的實現代碼高亮功能提供基礎，而 toc 則容許咱們自動生成目錄（在之後會介紹）。

來測試一下效果，進入後臺，此次咱們發佈一篇用 Markdown 語法寫的測試文章看看，你可使用如下的 Markdown 測試代碼進行測試，也能夠本身書寫你喜歡的 Markdown 文本。假設你是 Markdown 新手參考一下這些教程，必定學一下，保證你能夠在 5 分鐘內掌握經常使用的語法格式，而之後對你寫做受用無窮。可謂充電五分鐘，通話 2 小時。如下是我學習中的一些參考資料：

• Markdown——入門指南
• Markdown 語法說明 (簡體中文版)

# 一級標題

## 二級標題

### 三級標題

- 列表項1
- 列表項2
- 列表項3

> 這是一段引用

​```python def detail(request, pk): post = get_object_or_404(Post, pk=pk) post.body = markdown.markdown(post.body, extensions=[ 'markdown.extensions.extra', 'markdown.extensions.codehilite', 'markdown.extensions.toc', ]) return render(request, 'blog/detail.html', context={'post': post}) ​複製代碼

**若是你發現沒法顯示代碼塊，即代碼沒法換行，請檢查代碼塊的語法是否書寫有誤。代碼塊的語法如上邊的測試文本中最後一段所示。**

你可能想在文章中插入圖片，目前能作的且推薦作的是使用外鏈引入圖片。好比將圖片上傳到七牛雲這樣的雲存儲服務器，而後經過 Markdown 的圖片語法將圖片引入。Markdown 引入圖片的語法爲：`![圖片說明](圖片連接)`。

## safe 標籤

咱們在發佈的文章詳情頁沒有看到預期的效果，而是相似於一堆亂碼同樣的 HTML 標籤，這些標籤本應該在瀏覽器顯示它自己的格式，可是 Django 出於安全方面的考慮，任何的 HTML 代碼在 Django 的模板中都會被轉義（即顯示原始的 HTML 代碼，而不是經瀏覽器渲染後的格式）。爲了解除轉義，只需在模板標籤使用 `safe` 過濾器便可，告訴 Django，這段文本是安全的，你什麼也不用作。在模板中找到展現博客文章主體的 {{ post.body }} 部分，爲其加上 safe 過濾器，{{ post.body|safe }}，大功告成，這下看到預期效果了。

safe 是 Django 模板系統中的過濾器（Filter），能夠簡單地把它當作是一種函數，其做用是做用於模板變量，將模板變量的值變爲通過濾器處理事後的值。例如這裏 {{ post.body|safe }}，原本 {{ post.body }} 經模板系統渲染後應該顯示 body 自己的值，可是在後面加上 safe 過濾器後，渲染的值再也不是body 自己的值，而是由 safe 函數處理後返回的值。過濾器的用法是在模板變量後加一個 | 管道符號，再加上過濾器的名稱。能夠連續使用多個過濾器，例如 {{ var|filter1|filter2 }}。

![Markdown 測試](https://user-gold-cdn.xitu.io/2017/5/17/d54161784413c00de35d93f19569d2e8)

## 代碼高亮

程序員寫博客免不了要插入一些代碼，Markdown 的語法使咱們容易地書寫代碼塊，可是目前來講，顯示的代碼塊裏的代碼沒有任何顏色，很不美觀，也難以閱讀，要是可以像咱們的編輯器裏同樣讓代碼高亮就行了。雖然咱們在渲染時使用了 codehilite 拓展，但這只是實現代碼高亮的第一步，還須要簡單的幾步才能達到咱們的最終目的。

### 安裝 Pygments

首先咱們須要安裝 Pygments，**激活虛擬環境**，運行： `pip install Pygments` 安裝便可。

搞定了，雖然咱們除了安裝了一下 Pygments 什麼也沒作，但 Markdown 使用 Pygments 在後臺爲咱們作了不少事。若是你打開博客詳情頁，找到一段代碼段，在瀏覽器查看這段代碼段的 HTML 源代碼，能夠發現 Pygments 的工做原理是把代碼切分紅一個個單詞，而後爲這些單詞添加 css 樣式，不一樣的詞應用不一樣的樣式，這樣就實現了代碼顏色的區分，即高亮了語法。爲此，還差最後一步，引入一個樣式文件來給這些被添加了樣式的單詞定義顏色。

### 引入樣式文件

在項目的 blog\static\blog\css\highlights\ 目錄下應該能看到不少 .css 樣式文件，這些文件是用來提供代碼高亮樣式的。選擇一個你喜歡的樣式文件，在 base.html 引入便可（別忘了使用 static 模板標籤）。好比我比較喜歡 github.css 的樣式，那麼引入這個文件：

```html
templates/base.html

...
<link rel="stylesheet" href="{% static 'blog/css/pace.css' %}">
<link rel="stylesheet" href="{% static 'blog/css/custom.css' %}">
...
+ <link rel="stylesheet" href="{% static 'blog/css/highlights/github.css' %}">複製代碼

這裏 + 號表示添加這行代碼。好了，看看效果，大功告成，終於能夠愉快地貼代碼了。

代碼高亮

注意：若是你按照教程中的方法作完後發現代碼依然沒有高亮，請依次檢查如下步驟：

1. 確保在渲染文本時添加了 markdown.extensions.codehilite 拓展，詳情見上文。
2. 確保安裝了 Pygments。
3. 確保代碼塊的 Markdown 語法正確，特別是指明該代碼塊的語言類型，具體請參見上文中 Markdown 的語法示例。
4. 在瀏覽器端代碼塊的源代碼，看代碼是否被 pre 標籤包裹，而且代碼的每個單詞都被 span 標籤包裹，且有一個 class 屬性值。若是沒有，極有多是前三步中某個地方出了問題。
5. 確保用於代碼高亮的樣式文件被正確地引入，具體請參見上文中引入樣式文件的講解。
6. 有些樣式文件可能對代碼高亮沒有做用，首先嚐試用 github.css 樣式文件作測試。

總結

本章節的代碼位於：Step9: markdown and code highlight supported。

若是遇到問題，請經過下面的方式尋求幫助。

• 在 支持 Markdown 語法和代碼高亮 - 追夢人物的博客 的評論區留言。
• 將問題的詳細描述經過郵件發送到 djangostudyteam@163.com，通常會在 24 小時內回覆。