发现很多开源的项目文档,技术说明文档都是使用 mkdocs 构建,自己也了解了一下,确实很简单,快速。它的主题也很简洁,大方,作为技术项目说明或者笔记文档是相当合适的。
构建部署流程大致如下,详细可以参考官方完整指南。
环境:
- 支持Windows/Linux/macOS
- 需要安装 Python 2.7 +
- 需要 pip
1、安装MkDocs
$ pip install mkdocs
运行 mkdocs help
可以检查是否正确安装。
2、输入以下命令构建项目
$ mkdocs new project
project
是指项目名,你要在那个目录下创建,就切换到那个目录下 Windows的cmd 命令行和Linux的终端命令都是类似操作。
构建好的项目里有一个配置文件 mkdocs.yml
, 和一个包含文档源码的 docs
文件夹. 在 docs
文件夹里包含了一个名为 index.md
的文档.
3、启动内建服务器,进行预览
$ mkdocs serve
它会自动使用8000 端口,在浏览器中打开<http://127.0.0.1:8000/>
就可以完成效果的预览。
之后就是修改配置文件 mkdocs.yml
,自己可以添加一些配置信息,包括站点名称,文档页面等,很简单。
4、使用以下命令,创建新的页面
$ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
其实根本不用那么麻烦,在Windows下只用像创建文件目录那样操作即可,所有的文件都在docs
文件目录内。
5、主要是修改配置文件 mkdocs.yml
,这个决定了你的站点结构。
site_name: LYDSDOCS
nav:
- Home: index.md
- CSDocs:
- 操作系统: csdocs/OSNotes.md
- 数据结构: csdocs/data-structure.md
- 软件工程: csdocs/software.md
- About: about.md
theme: readthedocs
6、站点生成
$ mkdocs build
该命令创建了一个 site
新目录. 里面的文件就是你的站点资源文件,你可以把这些文件部署到服务器上或者github page上,就可以进行访问了。
大概流程就这些,其实和 hexo 生成站点差不多,一些具体的细节可以参考官方文档。MkDocs 中文文档