写在前面，如果您是有搭建私有文档平台的打算那么这篇文章是提供了一种方案，但如果仅仅用于内部分享或简单的短暂文档那paperen安利给你腾讯文档或showdoc

废话不多说，马上进入主题

目的：搭建一个对可使用个人域名，维护简单而且自动更新的文档站点

用到的组件/技术

  • mkdocs
  • git hook
  • apache/nginx等（nginx会更合适）

关于mkdocs（Markdown 项目文档工具）详细介绍

安装mkdocs

需要 Python 和 Python package manager pip 来安装 MkDocs . 可以通过以下命令查看是否安装了上述依赖:

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

MkDocs 支持 Python 2.6, 2.7, 3.3 和 3.4.

使用 pip 安装 mkdocs :

$ pip install mkdocs

mkdocs已经安装到你的系统. 运行 mkdocs help 以检查是否正确安装.

$ mkdocs help
mkdocs [help|new|build|serve|gh-deploy] {options}

上面直接抄的官方安装说明，简单来说就是需要先安装好python（2.6, 2.7, 3.3 和 3.4），之后再安装pip，最后通过pip安装mkdocs

目录与文档编写

关于目录打开一下mkdocs.yml文件看看就可以了解到如何新建菜单的

site_name: MkLorum
pages:
- [index.md, Home]
- [about.md, About]

如有增加页面只需按照- [xxx.md, xxx]加到pages节点下即可，所有的md文件都存放在docs目录

对于md文件那就很熟悉了，使用markdown语法编写即可，markdown语法学习

生成站点（生成html）

mkdocs build

很简单就一条命令，就能生成整个静态站点，会出来一个site目录，你可以将site目录打包发给别人或直接搭建起一个站点即可

回到一开始的初衷。咱们有一点必需要实现的就是自动更新，你总不会希望每次本地更改后生成html然后再上传到服务器这么麻烦吧？同时咱们的文档其他同事也可以编写新增，所以总不能让其本地也弄一个mkdocs，那恐怕是活活给开发人员增加了工作量降低了幸福感，paperen想的就是一旦他会md语法，会使用git那么他就能编写文档

要实现的目标并不复杂，思路有两个：

  1. 服务器上crontab+git pull
  2. git hook+钩子处理脚本

因为实际情况使用git hook的话需要提供http接口，所以paperen为了简单使用了第一种方案，就是服务器上通过crontab定时任务对文档站点进行自动发布更新

服务器上也需要安装好python与mkdocs，mkdocs的目录是通过git进行版本管理的，也就是说咱们本地修改的一旦提交，那么通过服务器上的定时任务进行git pull即可更新服务器上的md文件，然后再mkdocs build即可，那么当然site目录需要放到apache/nginx的配置作为某个域名的站点根目录（注意这里仅仅针对site目录）

这里paperen贴一下定时脚本供参考

#!/usr/bin/env bash

cd {mkdcos所在目录}
r=`git pull`
[[ $r =~ "Already up-to-date" ]] && exit
mkdocs build

关于上传图片与文件

发散一下，由于实际使用中会遇到需要上传图片或附件的功能，这个需求其实也不复杂但对于编写文档而言需要手动敲入一个专门用于图片或附件的域名，比如：http://xxxxx/1.png，这里xxxxx就是一个固定域名

解决办法：

同样使用回git目录，在mkdocs目录中创建一个目录叫upload，那么如果编写文档时需要插入图片，在本地时将图片放到upload目录，在文档中通过http://xxxxx/域名开头的绝对URL来引用图片或附件；服务器上将upload目录设置为一个单独域名的站点根目录，比如：attach.xxxx.com

希望上述解决方案能帮助您建立一个简单的私有文档中心站点