MkDocs构建项目文档流程

发现很多开源的项目文档,技术说明文档都是使用 mkdocs 构建,自己也了解了一下,确实很简单,快速。它的主题也很简洁,大方,作为技术项目说明或者笔记文档是相当合适的。

构建部署流程大致如下,详细可以参考官方完整指南。

环境:

  • 支持Windows/Linux/macOS
  • 需要安装 Python 2.7 +
  • 需要 pip

1、安装MkDocs

1
$ pip install mkdocs

运行 mkdocs help 可以检查是否正确安装。

2、输入以下命令构建项目

1
$ mkdocs new project

project 是指项目名,你要在那个目录下创建,就切换到那个目录下 Windows的cmd 命令行和Linux的终端命令都是类似操作。

构建好的项目里有一个配置文件 mkdocs.yml, 和一个包含文档源码的 docs 文件夹. 在 docs 文件夹里包含了一个名为 index.md 的文档.

3、启动内建服务器,进行预览

1
$ mkdocs serve

它会自动使用8000 端口,在浏览器中打开<http://127.0.0.1:8000/>就可以完成效果的预览。

之后就是修改配置文件 mkdocs.yml ,自己可以添加一些配置信息,包括站点名称,文档页面等,很简单。

4、使用以下命令,创建新的页面

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

其实根本不用那么麻烦,在Windows下只用像创建文件目录那样操作即可,所有的文件都在docs 文件目录内。

5、主要是修改配置文件 mkdocs.yml,这个决定了你的站点结构。

1
2
3
4
5
6
7
8
9
10
11
12
site_name: LYDSDOCS

nav:
- Home: index.md
- CSDocs:
- 操作系统: csdocs/OSNotes.md
- 数据结构: csdocs/data-structure.md
- 软件工程: csdocs/software.md

- About: about.md

theme: readthedocs

6、站点生成

1
$ mkdocs build

该命令创建了一个 site 新目录. 里面的文件就是你的站点资源文件,你可以把这些文件部署到服务器上或者github page上,就可以进行访问了。

大概流程就这些,其实和 hexo 生成站点差不多,一些具体的细节可以参考官方文档。MkDocs 中文文档