整合營銷服務商
電腦端+手機端+微信端=數據同步管理
免費咨詢熱線：
電腦端+手機端+微信端=數據同步管理
免費咨詢熱線：
最近準備搭建一個簡單的文檔平臺，用于組內的文檔管理。作為一個程序員，大多數情況下咱們寫文檔使用的都是markdown語法，比如wiki、hexo、github，然后在瀏覽器上展示。
目前大部分的編輯器都有自己的markdown插件并支持實時預覽，如下圖，
圖1
此圖是vscode編輯器，左側是markdown文件，右側是實時預覽的界面，咱們這次的目標就是將markdown在瀏覽器上展示成這個樣式。
為了將markdown在瀏覽器上展示就必須先將markdown轉化為html，有了明確的需求就可以去網上搜尋一下工具，我們很容易就能找到一個使用非常頻繁的工具——marked。
圖2
如圖2，它支持在頁面中編譯markdown代碼，但是我們更希望先在后臺完成編譯的工作再將編譯的產物放到頁面中使用，這樣頁面的性能會提示一丟丟，因此我們使用它的node方式。
圖3
如圖3，node編譯markdown的步驟也十分簡單，僅需以下幾步，
圖4
如圖4，左側是markdown編譯后的html，右側是在瀏覽器中展示的情況，此時完全沒有任何樣式，所以我們還需要為它配置主題。我們選用最流行的樣式——github-markdown-css，把它引入到文件中，再看看效果。
圖5
現在頁面已經有樣式了，和github的readme展示的樣式一樣，但是你會發現兩個問題，
注意：編譯產物最外層需要包一層容器，容器的class名字為markdown-body，否則樣式不生效。
為了解決上面第一個問題，我們將marked模塊換成markdown-it模塊，用法如下，
圖6
此時markdown的大部分語法都已經支持了，但仍有個別語法不支持，不過不要緊，我們可以將markdown-it的html參數設置為true，這樣用戶可以直接用html語法寫markdown。
代碼塊沒有高亮是不可接受的，這會讓同志們的瀏覽欲望大大降低。對比了一下highlight.js，我選擇了prism.js。不為別的，就是因為它滿足了我的要求。有人說prismjs比highlight.js對樣式控制的更精細，不過I don't care it。
圖7
如圖7，我一眼就看中了這個主題，有趣。那還等什么，直接把js和css都down下來，引入頁面。現在咱們再去看看效果，如下圖，
圖8
和我的編輯器主題一樣。
到這里我們已經完成了我們的需求。
將markdown轉化為html其實就兩步，一是選擇編譯工具，需要盡可能多的支持markdown語法，二是選主題，需要看著養眼。
喜歡我的文章就關注我吧，有問題可以發表評論，我們一起學習，共同成長！
者：HelloGitHub-追夢人物
文中涉及的示例代碼，已同步更新到HelloGitHub-Team 倉庫[1]
為了讓博客文章具有良好的排版，顯示更加豐富的格式，我們使用 Markdown 語法來書寫博文。Markdown 是一種 HTML 文本標記語言，只要遵循它約定的語法格式，Markdown 的解析工具就能夠把 Markdown 文檔轉換為標準的 HTML 文檔，從而使文章呈現更加豐富的格式，例如標題、列表、代碼塊等等 HTML 元素。由于 Markdown 語法簡單直觀，不用超過 5 分鐘就可以輕松掌握常用的標記語法，因此大家青睞使用 Markdown 書寫 HTML 文檔。下面讓我們的博客也支持使用 Markdown 寫作。
安裝 Python Markdown
將 Markdown 格式的文本解析成標準的 HTML 文檔是一個復雜的工程，好在已有好心人幫我們完成了這些工作，直接拿來使用即可。首先安裝 Markdown，這是一個 Python 第三方庫，在項目根目錄下運行命令 pipenv install markdown。
在 detail 視圖中解析 Markdown
將 Markdown 格式的文本解析成 HTML 文本非常簡單，只需調用這個庫的 markdown 方法。我們書寫的博客文章內容存在 Post 的 body 屬性里，回到我們的詳情頁視圖函數，對 post 的 body 的值做一下解析，把 Markdown 文本轉為 HTML 文本再傳遞給模板：
blog/views.py
import markdown
from django.shortcuts import get_object_or_404, render
from .models import Post
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})
這樣我們在模板中顯示 {{ post.body }} 的時候，就不再是原始的 Markdown 文本了，而是解析過后的 HTML 文本。注意這里我們給 markdown 解析函數傳遞了額外的參數 extensions，它是對 Markdown 語法的拓展，這里使用了三個拓展，分別是 extra、codehilite、toc。extra 本身包含很多基礎拓展，而 codehilite 是語法高亮拓展，這為后面的實現代碼高亮功能提供基礎，而 toc 則允許自動生成目錄（在以后會介紹）。
來測試一下效果，進入后臺，這次我們發布一篇用 Markdown 語法寫的測試文章看看，你可以使用以下的 Markdown 測試代碼進行測試，也可以自己書寫你喜歡的 Markdown 文本。假設你是 Markdown 新手請參考一下這些教程，一定學一下，保證你可以在 5 分鐘內掌握常用的語法格式，而以后對你寫作受用無窮。可謂充電 5 分鐘，通話 2 小時。以下是我學習中的一些參考資料：
?Markdown——入門指南[2]
?Markdown 語法說明[3]
# 一級標題
## 二級標題
### 三級標題
- 列表項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 引入圖片的語法為：。
我們在發布的文章詳情頁沒有看到預期的效果，而是類似于一堆亂碼一樣的 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 的語法使我們容易地書寫代碼塊，但是目前來說，顯示的代碼塊里的代碼沒有任何顏色，很不美觀，也難以閱讀，要是能夠像代碼編輯器里一樣讓代碼高亮就好了。
代碼高亮我們借助 js 插件來實現，其原理就是 js 解析整個 html 頁面，然后找到代碼塊元素，為代碼塊中的元素添加樣式。我們使用的插件叫做 highlight.js 和 highlightjs-line-numbers.js，前者提供基礎的代碼高亮，后者為代碼塊添加行號。
首先在 base.html 的 head 標簽里引入代碼高亮的樣式，有多種樣式供你選擇，這里我們選擇 GitHub 主題的樣式。樣式文件直接通過 CDN 引入，同時在 style 標簽里自定義了一點元素樣式，使得代碼塊的顯示效果更加完美。
<head>
...
<link rel="stylesheet">
<style>
.codehilite {
padding: 0;
}
/* for block of numbers */
.hljs-ln-numbers {
-webkit-touch-callout: none;
-webkit-user-select: none;
-khtml-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
text-align: center;
color: #ccc; ~
color: #ccc;
border-right: 1px solid #CCC;
vertical-align: top;
padding-right: 5px;
}
.hljs-ln-n {
width: 30px;
}
/* for block of code */
.hljs-ln .hljs-ln-code {
padding-left: 10px;
white-space: pre;
}
</style>
</head>
然后是引入 js 文件，因為應該等整個頁面加載完，插件再去解析代碼塊，所以把 js 文件的引入放在 body 底部：
<body> <script src="https://cdn.bootcss.com/highlight.js/9.15.8/highlight.min.js"></script> <script src="https://cdn.bootcss.com/highlightjs-line-numbers.js/2.7.0/highlightjs-line-numbers.min.js"></script> <script> hljs.initHighlightingOnLoad(); hljs.initLineNumbersOnLoad(); </script> </body>
非常簡單，通過 CDN 引入 highlight.js 和 highlightjs-line-numbers.js，然后初始化了兩個插件。再來看下效果，非常完美！
References
[1] HelloGitHub-Team 倉庫: https://github.com/HelloGitHub-Team/HelloDjango-blog-tutorial
[2] Markdown——入門指南: http://www.jianshu.com/p/1e402922ee32/
[3] Markdown 語法說明: http://www.appinn.com/markdown/
歡迎關注 HelloGitHub 公眾號，獲取更多開源項目的資料和內容
『講解開源項目系列』啟動——讓對開源項目感興趣的人不再畏懼、讓開源項目的發起者不再孤單。跟著我們的文章，你會發現編程的樂趣、使用和發現參與開源項目如此簡單。歡迎聯系我們給我們投稿，讓更多人愛上開源、貢獻開源～
## Markdown-it-py庫詳細介紹
在日常的軟件開發和內容創作中，Markdown已經成為了一種廣泛使用的輕量級標記語言。它簡潔、易讀易寫，并且支持豐富的擴展功能，因此受到了廣大開發者和寫作者的喜愛。在Python開發領域，有一個非常流行的Markdown解析器庫就是markdown-it-py。本文將詳細介紹markdown-it-py庫的使用方法、特性以及如何集成到你的項目中。
markdown-it-py是一個用于解析和渲染Markdown文本的Python庫。它基于流行的JavaScript庫markdown-it開發而來，提供了類似的功能和靈活的插件擴展機制。通過markdown-it-py，你可以將Markdown格式的文本解析為HTML或其他格式，或者從HTML轉換為Markdown。
首先，你需要通過pip安裝markdown-it-py庫：
pip install markdown-it-py
安裝完成后，你就可以在你的Python項目中引入并使用它了。
讓我們來看一個簡單的例子，演示如何使用markdown-it-py來解析Markdown文本并將其轉換為HTML：
from markdown_it import MarkdownIt
# 創建MarkdownIt實例
md=MarkdownIt()
# 要解析的Markdown文本
markdown_text="""
# 這是標題
這是一個 **粗體** 和 *斜體* 文本示例。
- 列表項 1
- 列表項 2
"""
# 將Markdown轉換為HTML
html_content=md.render(markdown_text)
print(html_content)
在上面的例子中，我們首先創建了一個MarkdownIt的實例md，然后通過render方法將Markdown格式的文本markdown_text轉換為HTML格式的html_content。運行代碼后，html_content將包含以下內容：
<h1>這是標題</h1>
<p>這是一個 <strong>粗體</strong> 和 <em>斜體</em> 文本示例。</p>
<ul>
<li>列表項 1</li>
<li>列表項 2</li>
</ul>
markdown-it-py支持通過插件擴展其功能。例如，你可以添加代碼高亮、表格支持、自定義語法等功能。以下是一個添加代碼高亮插件的示例：
from markdown_it.plugins import PluginPygments
# 創建MarkdownIt實例
md=MarkdownIt()
# 添加代碼高亮插件
md.use(PluginPygments())
# 要解析的Markdown文本
markdown_text="""
```python
print("Hello, World!")
"""
html_content=md.render(markdown_text)
print(html_content)
```
通過PluginPygments插件，我們可以輕松地實現代碼塊的語法高亮效果。
markdown-it-py是一個功能強大且易于使用的Markdown解析器庫，它為Python開發者提供了處理Markdown文本的便捷方法。無論是用于構建靜態網頁、生成文檔，還是集成到自動化腳本中處理文本，markdown-it-py都能夠滿足你的需求。通過本文的介紹，希望能夠幫助你更好地理解和使用這個優秀的工具。
*請認真填寫需求信息，我們會在24小時內與您取得聯系。
