使用mkdocs实时发布项目文档

MkDocs


 

MkDocs 是一个用于创建项目文档的 快速, 简单 , 完美华丽 的静态站点生成器. 文档源码使用 Markdown 来撰写, 用一个 YAML 文件作为配置文档。

虽然mkdocs现在还处于开发阶段,但是他所展现出来的特色确实很有吸引力,特别是他的实时发布功能。

官方文档

MkDocs的安装

MkDocs需要python和 Python package manager pip 环境,并且版本2.6以上,但是在2.6.6版本下安装时会提示缺少扩展包,升级到2.10后解决,所以建议尽量使用更新版本的python

#安装依赖
yum install openssl openssl-devel zlib zlib-devel -y

$ wget http://python.org/ftp/python/2.7.3/Python-2.7.3.tar.bz2  
$ tar -jxvf Python-2.7.3.tar.bz2 
$ cd Python-2.7.3
$ make && make install

$ ./Python-2.7.3/python --version
Python 2.7.2
$ wget https://bootstrap.pypa.io/get-pip.py
$ ./Python-2.7.3/python get-pip.py
$ pip --version
pip 1.5.2
$ pip install mkdocs

安装完mkdocs后使用 mkdocs –help 以检查是否正确安装

开始使用

新建项目

$ mkdocs new my-project
$ cd my-project

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

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

$ mkdocs serve
Running at: http://127.0.0.1:8000/

在浏览器中打开 http://127.0.0.1:8000/ , 可以看到结果页面screenshot

 

如果需要用到时时发布只需把mkdocs serve运行于后台即可,通过–dev-addr来指定ip和端口

nohup mkdocs serve --dev-addr 10.0.18.19:8000

也可以通过mkdocs build 来生成静态html页面

自定义模板

参考官方文档

Mkdocs支持中文搜索

1.下载支持中文的lunr.js替换mkdocs自带的lunr.js

cp ./lunr.js /usr/local/lib/python2.7/site-packages/mkdocs/assets/search/mkdocs/js/lunr-0.5.7.min.js

2.修改search.py ,添加ensure_ascii=False 禁止将中文字符串转为ascii编码,修改完之后,使用python -m py_compile search.py 命令编译一下search文件,然后将新的search.pysearch.pyc(编译文件)替换掉旧的即可

vim /usr/local/lib/python2.7/site-packages/mkdocs/search.py

修改如下一行为:

 return json.dumps(page_dicts, sort_keys=True,ensure_ascii=False, indent=4)

 

 

P.s Linx下如果遇到忘记命令怎么使用或者不熟悉的情况,学会使用 man 或者   –help   常常会用意外收获

“使用mkdocs实时发布项目文档”的2个回复

  1. Hi,根据你的教程,并没有设置成功,提示 404,实际上已经放到相应的目录下了,有邮箱可以进一步沟通吗?

发表评论

电子邮件地址不会被公开。 必填项已用*标注