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 文件夹,该文件夹包含了编译出来的静态网页文件。
接下来你要做的就是将这些文件直接上传到你的网站上即可食用。