使用Mkdocs构建你的项目文档
使用Mkdocs构建你的项目文档
环境搭建
安装必需软件
作者是在windows下安装的，如果是linux或mac用户，官网有更详细的安装说明。
windows 10 x64
当然还有广大的windows 7/8 用户，也是适用的。
python 3.4 x86版本(必备依赖)
下载地址：https://www.python.org/downloads/release/python-344rc1/
pip(pyton包管理器)
下载地址：https://pypi.python.org/pypi/pip
下载文件并解压到某个文件夹下，并使用CMD进入到解压后的文件夹目录
执行安装命令：
cd C:\Python34\pip-9.0.1
C:\Python34\pip-9.0.1>python setup.py install
安装mkdocs(把markdown转成静态html)
pip install mkdocs
端口被占用
开启MkDocs的服务器，报以下错：[WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试。
原因是默认的8000端口被占用，在官网文档中找到修改端口的方法：
https://markdown-docs-zh.readthedocs.io/zh_CN/latest/user-guide/configuration/
例如：我修改端口号为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
安装部分参考文章：http://www.cnblogs.com/yuanzm/p/4089856.html
编辑站点
使用markdown格式编写文档，并在mkdocs.yml 中组织目录结构
关于markdown的知识，可以参考我的博客：Markdown(MD)写作
mkdocs.yml的配置信息，请参考：https://markdown-docs-zh.readthedocs.io/zh_CN/latest/#_10
生成站点
生成静态的html，执行以下命令会创建一个site目录，并把生成后的静态html放在site目录。你可以对这些静态html进行版本控制。
mkdocs build
PS.如果你是托管在github上，那么使用gh-deploy也许更适合你。
发布站点
如果你的网站是托管在github在，那么事情会变的很简单
示例：默认发布到gh-pages分支，并在生成静态html时，清理不存在的文件
mkdocs gh-deploy --clean
deploy文档：http://www.mkdocs.org/user-guide/deploying-your-docs/
建议在开发阶段使用mkdocs serve
发布阶段使用 mkdocs gh-deploy
MkDocs中文文档：https://markdown-docs-zh.readthedocs.io/zh_CN/latest/#mkdocs
