使用Mkdocs构建你的项目文档

环境搭建

安装必需软件

作者是在windows下安装的，如果是linux或mac用户，官网有更详细的安装说明。

windows 10 x64

当然还有广大的windows 7/8 用户，也是适用的。

python 3.4 x86版本(必备依赖)

下载地址：

pip(pytone包管理器)

下载地址：

下载文件并解压到某个文件夹下，并使用CMD进入到解压后的文件夹目录

执行安装命令：

cd C:\Python34\pip-9.0.1C:\Python34\pip-9.0.1>python setup.py install

安装mkdocs(把markdown转成静态html)

pip install mkdocs

端口被占用

开启MkDocs的服务器，报以下错：[WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试。

原因是默认的8000端口被占用，在官网文档中找到修改端口的方法：

例如：我修改端口号为8001

:: Run on port 8001, accessible over the local network.(http://127.0.0.1:8001/) , if 8000 port is used by other.mkdocs serve --dev-addr=0.0.0.0:8001

安装部分参考文章：

编辑站点

使用markdown格式编写文档，并在mkdocs.yml 中组织目录结构

关于markdown的知识，可以参考我的博客：

mkdocs.yml的配置信息，请参考：

生成站点

生成静态的html，执行以下命令会创建一个site目录，并把生成后的静态html放在site目录。你可以对这些静态html进行版本控制。

mkdocs build

PS.如果你是托管在github上，那么使用gh-deploy也许更适合你。

发布站点

如果你的网站是托管在github在，那么事情会变的很简单

示例：默认发布到gh-pages分支，并在生成静态html时，清理不存在的文件

mkdocs gh-deploy --clean

deploy文档：

建议在开发阶段使用mkdocs serve

发布阶段使用 mkdocs gh-deploy

MkDocs中文文档：