一种文库类网站建设思路.md

​### 背景
最近一直想做一个有很多维护者的知识文库（或者是wiki）式的网站，用来支撑我的PyDocs（python文库网）。寒假时虽然利用django写了一个小的博客、CMS类的网站，但是想要做到多维护者下的版本控制却是非常苦难，一直没想到如何实现，所以暂时放弃自研的方案。
然后挑选了一些wiki式的开源网站，像dokuwiki，都比较大、丑，而且逻辑不太符合自己的胃口，浅尝而止。

hello，mkdocs

自己在写Django的rest风格的api时接触到了rest_framework这个库，发现这个网站文档官网就是基于mkdocs的，很符合自己要求，便深入了解了下。

MkDocs 是一个用于创建项目文档的 快速, 简单 , 完美华丽 的静态站点生成器. 文档源码使用 Markdown 来撰写, 用一个 YAML 文件作为配置文档。通过mkdocs build可以构建完全的静态 HTML 站点 , 可以将它托管到你的服务器上。此外默认包含大量美观的主题. 可以从 bootstrap, readthedocs 和 12 款 bootswatch 主题中选择。

关于mkdocs的详细情况见：http://www.mkdocs.org/

我的设计

网站结构图如下：

- 首先新建一个github项目。
每个文档维护者通过github实现文档的管理，包括新增、修改和删除等操作。github的基本操作详见廖雪峰的教程,此处不重复叙述。

• 本地使用mkdocs进行文档编写和预览
  以我的电脑ubuntu为例，直接

sudo apt pip install makdocs

直接安装本地mkdocs环境，然后

mkdocs new my-project
cd my-project

新建一个项目，修改yml配置文件，再在相关目录下编写markdown文件，mkdocs serve本地预览，mkdocs build构建生成静态文件。
这其中设计到mkdocs的大量操作，详见mkdocs官网信息：mkdocs.org

• 代码push到github上面

$ echo "site/" >> .gitignore

忽略指定目录 /site,
然后就是git的一系列操作。此处忽略~

• 服务器端的操作
  git clone XXX
  mkdocs build
  然后就是crontab -e新建一个定时任务，每天定时从github上pull文档和配置文件，再利用mkdocs build生成静态文件。

• 其他一些补充
  同步邮件通知，可以用python写一个，通知每天的情况。
  写一个php的小页面，点一下，立即重复服务端的一系列操作

这样做的好处

1. 将版本控制和异常处理转嫁到github上面，不需要做太多逻辑上处理
2. 生成的全是静态文件，加载速度相对快一点
3. 更安全

后续整理后将所有脚本发布

效果图（pydocs.cn）