基於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，那么可以考慮使用本文所介紹的語法，以實現豐富多樣的渲染效果。
筆者建議：盡量使用傳統語法，只在必要時候才使用本文介紹的語法。因為排版簡潔、條理清晰才能帶來最舒服的閱讀感受。