部署参考文档

中文文档： https://markdown-docs-zh.readthedocs.io/zh_CN/latest/
英文文档： https://www.mkdocs.org/
GitHub： https://github.com/mkdocs/mkdocs

mkdocs模块安装

使用 pip 安装 mkdocs :

  1. $ pip install mkdocs 
  2. # mkdocs已经安装到你的系统. 运行 mkdocs help 以检查是否正确安装.
  3. $ mkdocs help 
  4. mkdocs [help|new|build|serve|gh-deploy] {options}

初始化新项目

输入以下命令以开始一个新项目.

  1. $ mkdocs new my-project 
  2. $ cd my-project

我们看一下已经创建的初始化项目。
python-mkdocs - 图1
有一个配置文件 mkdocs.yml, 和一个包含文档源码的 docs 文件夹. 在 docs 文件夹里包含了一个名为 index.md 的文档。

本地测试

MkDocs 包含了一个内建的服务器以预览当前文档，控制台切换当前目录到 mkdocs.yml 配置文件相同文件夹, 输入 mkdocs serve 命令以启动内建服务器:

  1. $ mkdocs serve

Running at: http://127.0.0.1:8000/
在浏览器中打开 http://127.0.0.1:8000/ , 你将看到以下页面:
python-mkdocs - 图2

修改配置

标题

内建服务器支持在配置文件,文档目录或主题发生改变时自动载入并重新生成文档.
编辑 docs/index.md 文件并保存. 刷新浏览器你将看到文档被同步更新.
现在可以开始编辑配置文件 mkdocs.yml 了. 把 site_name 改成其他内容并保存文档.
python-mkdocs - 图3
刷新浏览器你将看到网页标题已发生改变.
python-mkdocs - 图4

添加页面

编辑 doc/index.md 文档, 将默认标题改为 MkLorum, 刷新浏览器即可看到标题变化.
现在为文档添加第二个页面:

  1. $ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

要为文档添加导航条, 只需在配置文件中添加导航条需要的标题和排序即可:

  1. site_name: MkLorum
  2. pages: 
  3. - [index.md, Home] 
  4. - [about.md, About]

刷新浏览器即可看到 Home 和 About 导航栏目.

配置主题

可以在配置文件中修改文档主题. 在 mkdocs.yml 中添加如下内容:

  1. site_name:  MkLorum
  2. pages: 
  3. - [index.md, Home] 
  4. - [about.md, About] 
  5. theme: readthedocs 
  6. # 有很多主题可以切换

刷新浏览器即可看到 ReadTheDocs 主题已被应用.
python-mkdocs - 图5

站点生成

我们现在已经可以发布 MkLorum 文档了. 通过以下命令生成文档.

  1. $ mkdocs build

该命令创建了一个 site 新目录. 可以通过以下命令浏览该目录内容:

  1. $ ls site

about css fonts img index.html js
注意源码被分别输出为 index.html 和 about/index.html. 主题中的其他文件也被复制到了 site 目录中.
如果你使用 git 等版本控制系统, 你可能不希望提交构建之后的文档到版本库. 在 .gitignore 中添加 site/ 即可忽略该目录.
$ echo “site/“ >> .gitignore
如果你使用其他版本控制系统则需要查阅相关文档以确定如何忽略指定目录.
一段时间后, 可能有文件被从源码中移除了, 但是相关的文档仍残留在 site 目录中. 在构建命令中添加 —clean 参数即可移除这些文档.
$ mkdocs build —clean

发布

MkDocs 生成的文档只包含静态文件, 因此你可以将文档部署到任意地方.
GitHub project pages 、 Amazon S3 、云服务器。 只需上传 site 目录到你需要发布的位置即可.