MkDocs 文檔生成邏輯淺析

Markdown 和 MkDocs 簡介

Markdown 的語法簡潔明瞭、學習容易，並且功能比純文本更強，所以有不少人用它寫博客。世界上最流行的博客平臺 WordPress 和大型 CMS 如 Joomla 、Drupal 都能很好的支持 Markdown 。

MkDocs 是一個用於建立項目文檔的快速，簡單的靜態站點生成器。文檔源碼使用 Markdown 來撰寫，用一個 YAML 文件做爲配置文檔。

MkDocs 處理的是一系列的 Markdown 文檔，而後將 Markdown 文檔的內容解析出來，保存在 Python 字典中，最後 Jinja2 模板把內容生成爲 html 。

MkDocs 如何將 Markdown 內容解析出來？又是如何將文檔內容結構化的？

Markdown 文檔解析

使用 Python-Markdown 解析文件，而後返回 html_content ,table_of_contents ,meta 。對內容作了初步的處理，從 markdown 文件，轉換爲 Python 相關變量。

Python-Markdown 簡介
This is a Python implementation of John Gruber’s Markdown. It is almost completely compliant with the reference implementation, though there are a few very minor differences. See John’s Syntax Documentation for the syntax rules.

Markdown 文檔解析

YAML 配置文件

載入 YAML 的配置，將配置文件的內容讀取爲 Python 內容。

YAML是一種直觀的可以被電腦識別的的數據序列化格式，容易被人類閱讀，而且容易和腳本語言交互。YAML相似於XML，可是語法比XML簡單得多，對於轉化成數組或能夠hash的數據時是很簡單有效的。

YAML 配置文件

Python 字典

獲取頁面內容，從 markdown 中解析的內容，存入 Python 字典中，爲後續 Jinja2 的調用作準備。

Python 字典

Jinja2 內容生成

載入 Jinja2 模板，結合以前抽取的內容生成 HTML 文件。
Jinja2 是一個現代的，設計者友好的，仿照 Django 模板的 Python 模板語言。 它速度快，被普遍使用，而且提供了可選的沙箱模板執行環境保證安全。

Jinja2 內容生成

Jinja2 模板文件

toc.html 的代碼
模板文件中有以前的 Python 變量，好比 nav.item ，會被替換爲對應的內容。

Jinja2 模板文件

MkDocs 比較巧妙的實現了內容和表現的分離，雖然沒有數據庫，可是使用告終構化的 markdown 文件，解析爲 Python 內容，而後經過 Jinja2 模板，最後生成 HTML。

MkDocs http://www.mkdocs.org/

做者：不知道本身是誰（極光）

http://www.jianshu.com/p/c9410da484fb