基於mkdocs-material搭建個人純靜態部落格，沒有php，沒有mysql 如果你只是想安安靜靜的放一些技術文章，釋出到個人站點或github-pages，mkdocs-material很適合你

小慢哥的原創文章，歡迎轉載

• 本文僅是縮略，筆者已將詳細內容釋出到github上

• 可點選本文最後的"閱讀更多"進行訪問，或者在github上搜"cyent markdown"也可以看到

目錄

• 本文概述

• mkdocs-material介紹

• 安裝

• 初始化專案

• 修改主題

• 執行

• 釋出到GitHub pages

• 釋出到個人HTTP Server

• mkdocs.yml注意事項

• 新增頁面

• 新增擴充套件

• markdown語法

• 其他功能

• 最佳實踐

本文概述

mkdocs-material入門，包括安裝、執行、釋出至github-pages及個人站點

mkdocs-material介紹

符合google material ui規範的靜態文件網站生成器，使用markdown進行文件書寫

mkdocs

• python編寫的markdown直譯器、編譯器，帶有本地cli工具

• 自帶基於Tornado的小型http服務，用於本地除錯

• 內建一鍵式釋出至GitHub Pages

• 內建mkdocs風格、readthedocs風格的主題，並支援自定義主題

• 支援呼叫python模組實現語法及渲染的擴充套件

mkdocs-material

• python模組，符合google material ui規範的mkdocs自定義主題

• 針對特定語法、功能做了渲染優化

• 根據客戶端瀏覽器頁面尺寸自動縮放，對PC、移動裝置都友好

• 豐富的頁面配色，多達19種主體配色和16種懸停連結文字配色

• 支援中文搜尋

• 支援統計功能，如百度統計，谷歌統計

安裝

  pip install mkdocs mkdocs-material

若下載慢，可更換安裝源為豆瓣

  pip install --trusted-host pypi.douban.com -i   http://pypi.douban.com/simple/ mkdocs mkdocs-material

初始化專案

  mkdocs new my-project

會生成my-project目錄，進入該目錄裡，可以看到預設放置了一些檔案，包括mkdocs.yml，這是主配置檔案

修改主題

mkdocs.yml裡新增:

  theme:    name: material

執行

  # 在my-project目錄裡執行  mkdocs serve

通過瀏覽器訪問本地ip的8000埠（比如http://127.0.0.1:8000/） 檢視效果，如圖所示

釋出到GitHub pages

通過 mkdocs gh-deploy自動編譯出html併發布至GitHub pages，步驟如下

初始化repo

1.在github上建立一個repo，名字叫my-project（可以是其他名，這裡先假設叫my-project），建立repo時候選擇初始化帶有README.md 2.將repo同步到本地，使用git clone

匯入專案

1.將mkdocs根目錄（即my-project目錄）下的所有東西移到剛剛git clone下來的git目錄下 2.然後可以將最早建立的mkdocs根目錄（即my-project目錄）刪除了

釋出

在本地git目錄下執行

  mkdocs gh-deploy

釋出到個人HTTP Server

通過 mkdocs build編譯出html並手動同步至http server的根目錄

生成站點檔案

在git目錄下執行命令

  mkdocs build

命令執行完畢後可以看到site目錄

釋出至http server

將site目錄裡的所有東西拷貝到http server的根目錄下

mkdocs.yml注意事項

由於是yaml格式，因此首先要符合yaml的語法要求

docs下需要一個index.md，作為站點首頁

文件層次結構雖然可以很多層，但最佳實踐是控制在2層內，最多不要超過3層，否則展示會不夠友好

新增頁面

在my-project/docs/裡放置.md檔案，可以自行組織目錄結構

然後在mkdocs.yml裡新增，比如這樣:

  nav:    - 介紹: index.md    - 安裝:        - 本地環境搭建: install/local.md        - 釋出至GitHub Pages: install/github-pages.md        - 釋出至自己的HTTP Server: install/http-server.md    - 語法:        - 語法總覽: syntax/main.md        - 標題: syntax/headline.md        - 段落: syntax/paragraph.md

• 上面的index.md就是放置在my-project/docs/index.md

• 上面的local.md就是放置在my-project/docs/install/local.md

新增擴充套件

只有添加了擴充套件，才能完美使用mkdocs-material官方支援的所有markdown語法

mkdocs.yml裡新增:

  markdown_extensions:    - admonition    - codehilite:        guess_lang: false        linenums: false    - toc:        permalink: true    - footnotes    - meta    - def_list    - pymdownx.arithmatex    - pymdownx.betterem:        smart_enable: all    - pymdownx.caret    - pymdownx.critic    - pymdownx.details    - pymdownx.emoji:        emoji_generator: !!python/name:pymdownx.emoji.to_png    - pymdownx.inlinehilite    - pymdownx.magiclink    - pymdownx.mark    - pymdownx.smartsymbols    - pymdownx.superfences    - pymdownx.tasklist    - pymdownx.tilde

markdown語法

mkdocs-material支援幾十種markdown語法，有許多很酷炫的功能與效果，由於篇幅有限，無法在這一一展示，因此這裡僅列舉下所支援的主要語法

1.標題 2.段落 3.引用 4.表格 5.程式碼

• 行內

• 區塊

• 高亮

6.字型樣式

• 斜體,粗體,粗斜體

• 上標,下標

• 下劃線

• 橫線

• 下劃線+橫線

7.列表

• 無序列表

• 有序列表

• 任務列表

8.分割線 9.連結

• 普通連結

• 自動連結

• 錨點提示

10.圖片

• 行內式

• 參考式

11.轉義 12.高亮

• 程式碼高亮

• 背景高亮

13.註解

• 介紹

• 完整格式

• 空標題

• 無標題

• 無型別

• 摺疊

• 11種顏色樣式

• 巢狀

14.腳註 15.元資訊 16.數學公式

• 介紹

• 匯入js

• 用法

17.emoji

• 介紹

• 工作原理

• 最佳實踐

18.特殊符號 19.巢狀

• 介紹

• 註解-註解

• 列表-列表

• 引用-引用

• 註解-程式碼塊

• 列表-程式碼塊

• 引用-程式碼塊

• ×××區塊-程式碼

• 綠色區塊-程式碼

• 紅色區塊-程式碼

• 綠接紅區塊-程式碼

• 註解-列表-引用

• 列表-列表-引用

• 引用-引用-程式碼

其他功能

mkdocs-material本身還支援如下功能：

• 新增js，可用於站點統計（如百度統計，谷歌統計）

• 頁面以及跳轉文字的配色

• 中文搜尋

最佳實踐

如果希望自己所寫的markdown可以相容各個markdown編輯器，那麼只需瞭解markdown的傳統語法即可

如果想讓自己所寫的markdown釋出到web伺服器，例如GitHub Pages、自己搭建的HTTP Server，那麼可以考慮使用本文所介紹的語法，以實現豐富多樣的渲染效果。

筆者建議：儘量使用傳統語法，只在必要時候才使用本文介紹的語法。因為排版簡潔、條理清晰才能帶來最舒服的閱讀感受。

閱讀更多