
什么是 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