什么是 MkDocs
MkDocs（Markdown Documents）是一个快速、简单的静态网站生成器，用于将 Markdown 文档组织起来构建成有层次、美观的文档站点。
MkDocs 基于 Python 编写，也贯彻了 Python 里「简洁胜于复杂」的理念，与其他常见的静态网站生成器相比，无需繁琐的环境配置（如 Jekyll 涉及的 Bundler、Gems 等），所有配置都用只有简单的一个配置文件管理，并且当中配置项的内容也仅有一页文档。
MkDocs 见名知意就是为 Markdown 而生，根据 Markdown 格式将内容渲染成美观的文档，并通过目录层级关系对应文档的树状结构，使得当中所有的文档组织分明且层次递进。
环境安装
安装 Python
访问官网 https://www.python.org/ 安装对应环境的Python环境
安装 MkDocs
通过命令 pip install mkdocs 安装 MkDocs
pip 使用国内镜像源
在 pip 命令中使用 -i 参数来指定镜像地址，例如：
pip3 install mkdocs -i https://pypi.tuna.tsinghua.edu.cn/simple
设为默认
升级 pip 到最新的版本后进行配置：
python -m pip install --upgrade pip
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
如果您到 pip 默认源的网络连接较差，临时使用本镜像站来升级 pip：
python -m pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple --upgrade pip
其他国内镜像源
- 清华大学TUNA镜像源： https://pypi.tuna.tsinghua.edu.cn/simple
- 阿里云镜像源： http://mirrors.aliyun.com/pypi/simple/
- 中国科学技术大学镜像源： https://mirrors.ustc.edu.cn/pypi/simple/
- 华为云镜像源： https://repo.huaweicloud.com/repository/pypi/simple/
- 腾讯云镜像源：https://mirrors.cloud.tencent.com/pypi/simple/
快读上手
- 使用
mkdocs new <your-site-project-name>新建站点项目，比如我这里叫 mysite，则是mkdocs new mysite。 - 命令行切换到 mysite 目录下，并使用
mkdocs serve在本地运行。 - 打开浏览器，输入
localhost:8000，就能预览到 MkDocs 帮我们搭建好的文档站点了。
目录结构
my-projct
├── docs
│ ├── index.md
│ ├── notes
│ │ ├── mkdocs.md
│ │ └── python.md
│ └── demos
└── mkdocs.yml
- docs 文件夹就是用于存放我们所有的Markdown 格式的文档内容，当然我们也可根据自己的需要进一步用文件夹归类划分，这也是 MkDocs 运行时默认的根路径。我们也可以后续手动指定修改成其他目录。
- mkdocs.yml 该文件主要用于 MkDocs 的定制化配置的设置与管理。
- docs/index.md 该文档内容是必须要有的，它是整个 MkDocs 构建的首页入口
YAML 配置文件格式
YAML 是 YAML Ain’t Markup Language 的递归缩略语，也是一种人类可读（human-readable) 的数据序列化语言，其文件扩展名为 .yml 或 .yaml（官方推荐）。常被用作和 JSON 格式文件一样编写配置或存储相关数据内容。
我们只需要谨记以下三个核心元素的用法，就能应付大多数 YAML 配置需求，包括本文的主角 MkDocs：
- 键值对（Key-Value Pair）
- 缩进（indent）
- 同一层级下不能有重名键
键值对
键值对在 YAML 中的形式如下：name: 100gle
缩进
YAML 用 空格 缩进来表示层级关系，这区别于另一种流行配置格式 JSON 使用的花括号 {}，可能是受到了 Python 的影响。
family:
father:
name: foo
age: 100
child:
name: baz
age: 3
需要注意的是，空格（ASCII 码值为 32）有的时候会和 Tab 键产生的制表符（ASCII 码值为 9）混在一起，二者单从外观上来看无法分辨，因此为避免 YAML 解析错误，我们在编写时要遵循 YAML 官方缩进的要求使用 两个半角空格。
同一层级下不能有同名键 了解键值对和缩进值后，我们还需要注意的一点就是 YAML 不允许在同一层级下出现相同的键，例如：
father:
name: foo
age: 100
family:
father:
name: foo
age: 100
child:
name: baz
age: 3
father: foo
在这个例子中 father 和两个 family/father 键（行文方便起见，我这里会以文件路径的形式表现层级关系）虽然同名，但因为它们并不在一个层级中，因此并不会产生冲突。
但是在 family 中，第一个 family/father 会和第三个 family/father 产生冲突，因为它们同级且同名。
在 mkdocs.yml 中编写配置
添加站点信息
最开始在 mkdocs.yml 文件中填写的主要还是关于站点相关的信息。其中我们可以填写的有那么几个：
- site_name：站点名称
- site_url：站点 URL 链接
- site_author：站点作者
- site_description：站点描述
- copyright：版权信息
- repo_url：站点仓库 URL
其中，只有两个必须要填写的配置项就是 site_name 站点名称和 site_url 站点 URL 链接。例如：
site_name: "My Notes"
site_url: "http://<domain>:<port>/<project>"
除此之外的选项都是选填，如果填写了则 MkDocs 会将其作为元数据或元素渲染最后的 HTML 中。
添加文档路径
MkDocs 提供了让使用者能够自由安排文档层级结构或目录编排的设置，这将决定最后文档在站点中的编排效果如何。这里主要是通过 nav 项来进行配置：
nav:
- "index.md"
- user-guide:
- quickstart: "user-guide/quickstart.md"
- usage: "user-guide/how-to-use-MkDocs.md"
- "about.md"
- "license.md"
在该设置项中，使用了 YAML 所支持的列表语法，这和 Markdown 的无序列表语法是完全一致。默认情况下如果不指定键名，MkDocs 会自动根据列举的 Markdown 文件名字符串来确定最终该页面的名称如何；如果我们手动指定了键名，那么会优先以我们的键名为主，比如这里的 user-guide/usage 这一部分。
需要注意的是，前面对于 MkDocs 的快速介绍中我就有提到，MkDocs 默认会将项目目录下的 docs 目录作为默认的根路径，所以在 nav 设置中我们如果指定的是该目录下的其他内容，那么就是只需要填写相对路径。
这也是为什么在上述例子中的 user-guide 这一部分下的文档路径都不需要写成 docs/user-guide/XXXX.md 的原因。
同时，最终 MkDocs 也会根据 nav 配置的层级关系将内容的层级关系或包含关系一同渲染。
当然，如果你不想使用 MkDocs 的默认目录，那么你也可以通过修改 docs_dir 选项来指定对应的文件夹名称。但通常情况我们都不需要进行修改就已经能满足我们的基本需要了。
Material for MkDocs
Material for MkDocs 官网 https://squidfunk.github.io/mkdocs-material/
安装 mkdocs-material
pip install mkdocs-material -i https://pypi.tuna.tsinghua.edu.cn/simple
安装插件
mkdocs-audio
安装 mkdocs-audio
pip install mkdocs-audio -i https://pypi.tuna.tsinghua.edu.cn/simple
扫码分享收藏