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 文件夹，该文件夹包含了编译出来的静态网页文件。

接下来你要做的就是将这些文件直接上传到你的网站上即可食用。