基於mkdocs-material搭建個人靜態部落格

原文連結

基於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，那麼可以考慮使用本文所介紹的語法，以實現豐富多樣的渲染效果。

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

閱讀更多