MkDocs 安装&简单使用教程
因为在 Wiki 上写帮助文档，实在有点麻烦。
偶然看到了 CraftTweaker 的帮助文档，就知道了 MkDocs 这个玩意。
所以趁这次中考假我就研究了一下，发现还是很好用的。
安装 Python
要使用 MkDocs，首先需要安装 Python。
至于详细教程我到时候摸一篇文章介绍(Linux 下的安装)。
安装 MkDocs
MkDocs 必须用 pip 安装。
安装 MkDocs命令:
pip install mkdocs # 或者，下面这种指令格式也可以(Windows 环境下必须使用下面的) python -m pip install mkdocs
注意在使用诸如 pip 和 MkDocs 这种涉及到 Python 的指令在 Windows 环境下必须带 python -m(下文不再提示)。
安装完成后，测试一下安装是否正确:
>mkdocs --version # __main__.py, version 1.0.4 from (安装目录) (Python 3.7)
出现上面的提示则安装成功。
开始使用 MkDocs
随便找一个可以用于存放 MkDocs 项目文件的目录，执行以下命令
mkdocs new (项目名称) # INFO - Creating project directory: helpdocs # INFO - Writing config file: helpdocs\mkdocs.yml # INFO - Writing initial docs: helpdocs\docs\index.md
这样就创建好项目了。转到项目目录，执行以下命令即可运行(注意运行的是开发用服务器)。
mkdocs serve # INFO - Building documentation... # INFO - Cleaning site directory # [I 190728 18:06:15 server:296] Serving on http://127.0.0.1:8000 # [I 190728 18:06:15 handlers:62] Start watching changes # [I 190728 18:06:15 handlers:64] Start detecting changes
可以看到，MkDocs 已经运行于 127.0.0.1:8000。使用浏览器打开这个地址即可预览效果。注意这个预览是实时刷新的，如果你改了你项目的文件，那么预览会随时刷新。
项目文件结构
新建的项目默认有 mkdocs.yml 和 docs 文件夹。如果你编译过项目，则还会有 site 文件夹(编译的事情下文会提)。
mkdocs.yml 文件是项目的配置文件。站点的相关设置，和页面的添加等等均通过该文件指定。
下面展示了该配置文件中的一些基础设置项目。
site_name: (站点名称)
site_description: (站点注释)
site_author: (站点作者名称)
site_url: (站点地址)
copyright: (版权声明相关文本)
# nav 区域指定站点上能看到的页面。
# 下面的配置代码仅作示范。注意配置的页面对应的 MarkDown 源码文件必须存在。
nav:
- Index: index.md
- Page 1: page1.md
# 下面代表的是一组页面
- Page Group:
- Sub Page 1: subpage/page1.md
- Sub Page 2: subpage/page2.md
-About: about.md
docs 文件夹用于存放所有的文档文件的 Markdown 源码和图片相关文件。mkdocs.yml 的 nav 中指定的文件需要与该文件夹中的文件一一对应。
上面 mkdocs.yml 的实际效果:
更换主题(可选)
MkDocs 内建了 默认主题 和 ReadTheDocs 主题。
要启用 ReadTheDocs 主题，只需要在 mkdocs.yml 中加入下面设置即可。
theme: readthedocs
有关这两个主题的相关信息可以在这里找到。
更多主题可以在这里找到。由于主题数目太多，逐个介绍浪费篇幅，所以这里略过。
编译成静态网页
当你写完所有文档后，觉得预览效果不错，就需要将你写的文档转换为静态网页。
转到项目的根目录，执行下面的命令即可编译。
mkdocs build # INFO - Cleaning site directory # INFO - Building documentation to directory: (项目目录)\site
此时项目文件夹下会出现 site 文件夹，该文件夹包含了编译出来的静态网页文件。
接下来你要做的就是将这些文件直接上传到你的网站上即可食用。
