一种文库类网站建设思路

2016-3-19 pierre

背景

最近一直想做一个有很多维护者的知识文库(或者是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为例,直接

  1. sudo apt pip install makdocs

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

  1. mkdocs new my-project
  2. cd my-project

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

  • 代码push到github上面
  1. $ echo "site/" >> .gitignore

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

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

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

这样做的好处

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

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

效果图(pydocs.cn)



来自为知笔记(Wiz)


发表评论:

Powered by emlog 陕ICP备15016021 sitemap