●  本文仅是缩略，笔者已将详细内容发布到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种悬停链接文字配色
 ●   支持中文搜索

 ●  支持统计功能，如百度统计，谷歌统计

安装

1. pip install mkdocs mkdocs-material

若下载慢，可更换安装源为豆瓣

1. pip install --trusted-host pypi.douban.com -i

2. http://pypi.douban.com/simple/ mkdocs mkdocs-material

1. mkdocs new my-project

会生成my-project目录，进入该目录里，可以看到默认放置了一些文件，包括mkdocs.yml，这是主配置文件

修改主题

mkdocs.yml里添加:

1. theme:

2. name: material

1. # 在my-project目录里执行

2. 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.使用git clone将repo同步到本地

导入项目

1.将mkdocs根目录（即my-project目录）下的所有东西移到刚刚git clone下来的git目录下 2.然后可以将最早创建的mkdocs根目录（即my-project目录）删除了

发布

在本地git目录下执行

1. mkdocs gh-deploy

通过 mkdocs build编译出html并手动同步至http server的根目录

生成站点文件

在git目录下执行命令

1. mkdocs build

命令执行完毕后可以看到site目录

发布至http server

将site目录里的所有东西拷贝到http server的根目录下

mkdocs.yml注意事项

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

docs下需要一个index.md，作为站点首页

文档层次结构虽然可以很多层，但最佳实践是控制在2层内，最多不要超过3层，否则展示会不够友好

添加页面

在my-project/docs/里放置.md文件，可以自行组织目录结构

然后在mkdocs.yml里添加，比如这样:

1. nav:

2. - 介绍: index.md

3. - 安装:

4. - 本地环境搭建: install/local.md

5. - 发布至GitHub Pages: install/github-pages.md

6. - 发布至自己的HTTP Server: install/http-server.md

7. - 语法:

8. - 语法总览: syntax/main.md

9. - 标题: syntax/headline.md

10. - 段落: syntax/paragraph.md

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

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

添加扩展

只有添加了扩展，才能完美使用mkdocs-material官方支持的所有markdown语法

mkdocs.yml里添加:

1. markdown_extensions:

2. - admonition

3. - codehilite:

4. guess_lang: false

5. linenums: false

6. - toc:

7. permalink: true

8. - footnotes

9. - meta

10. - def_list

11. - pymdownx.arithmatex

12. - pymdownx.betterem:

13. smart_enable: all

14. - pymdownx.caret

15. - pymdownx.critic

16. - pymdownx.details

17. - pymdownx.emoji:

18. emoji_generator: !!python/name:pymdownx.emoji.to_png

19. - pymdownx.inlinehilite

20. - pymdownx.magiclink

21. - pymdownx.mark

22. - pymdownx.smartsymbols

23. - pymdownx.superfences

24. - pymdownx.tasklist

25. - pymdownx.tilde

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，那么可以考虑使用本文所介绍的语法，以实现丰富多样的渲染效果。

笔者建议：尽量使用传统语法，只在必要时候才使用本文介绍的语法。因为排版简洁、条理清晰才能带来最舒服的阅读感受。