MkDocs实现自动发布静态网站

原本使用的GitBook来发布静态博客（网站），但是，由于GitBook官方已经不再更新，且其默认主题确实不怎么漂亮，于是准备换个其它的。偶然间得知了Mkdocs，好像很符合我的要求：其功能的简洁，仅用来生成静态网站，不像gitbook还有其它的用途；默认主题就很不错，漂亮的外观，博客的布局（不像gitbook，那真是一本书...）。要切换过来，得可以方便的发布才行呀，于是参照之前写的Gitbook搭配Git实现自动发布静态网站的原理，写下这篇博客，并切换到mkdocs。

思路大概是这样的：远程服务器上建立mkdocs的Git裸仓，clone到本地，然后本地修改（增、删、改）文档后通过Git的push到远程的仓库，此时触发远程仓库的githooks，由githooks代码在远程服务器执行mkdocs build，生成静态文件到nginx所配置的网站的目录，以此实现本地更新文档后自动发布。

本教程的各个硬件如下

服务器：GCE，Ubuntu 1804
本地环境：Linux(win10 WSL)

服务器端安装并配置nginx

静态网站由nginx来承担功能，请参考Nginx简易教程安装并配置Nginx。

安装并配置MkDocs

注意：Mkdocs服务器端跟本地都需要安装。

安装方法可以参考mkdocs官方文档，也可以查阅mkdocs中文文档。安装方法分为包管理器安装和手动安装。

包管理器安装

部分Linux发行版的官方包里面已经有mkdocs，如此安装就很方便了，通过其包管理可以方便的完成安装，并自动安装其依赖的其它软件，比如python。我这使用的GCE的Ubuntu 1804包管理器支持安装mkdocs。

sudo apt install mkdocs

安装完成后，通过以下命令查看mkdocs的版本号，并验证安装是否成功：

mkdocs -V

我这显示的版本号是0.16.3，太老了，官方最新的版本为1.0.4。所以，放弃使用包管理，还得是手动安装才行。

手动安装

mkdocs基于python，所以得先安装python，然后通过其包管理pip来安装mkdocs。

安装python

一般来说，Linux基本都已经安装了python，只是版本高低的问题，但是Mkdocs支持2.7，因此基本不用可以去安装python。使用以下命令查看python的版本号并验证是否安装：

python3 -V

但是，其包管理器pip则未必安装。

安装pip

检查是否已经安装：

pip3 -V

已经安装的话，更新下：

pip3 install --upgrade pip

最新的python安装时，会自动安装上pip。如果没有安装的话，需要自行安装。这里使用第三方的脚本来安装最新的版本。

wget https://bootstrap.pypa.io/get-pip.py
sudo python3 get-pip.py

注意

需要注意sudo python3 get-pip.py这行命令中的python3,如果使用python3，则更改为python3，使用的是python2，这修改为python，如此才能将pip正确安装在对应的python版本中。

通过以下命令来查看版本号，并验证是否安装成功：

pip -V

pip 19.1.1 from /usr/local/lib/python2.7/dist-packages/pip (python 2.7)

安装mkdocs

完成以上步骤后，就可以通过pip来安装mkdocs了：

sudo pip install mkdocs

同样的，查看下版本号，并验证安装是否成功:

mkdocs -V

mkdocs, version 1.0.4 from /usr/local/lib/python2.7/dist-packages/mkdocs (Python 2.7)

新建mkdocs项目（仅服务器端）

在你期望的位置，新建一个mkdocs项目。我这里放在/home/mkdocs目录下：

mkdir /home/mkdocs
cd /home/mkdocs
sudo mkdocs new zimohan.com

其中的zimohan.com是新建项目的名称，将会在当前目录中新建一个以该名称命名的文件夹，为方便区分，建议命名为网站的域名。

安装并配置Git

安装git

与mkdocs一样，服务器端跟本地都要安装Git。一般来说，Linux的发行版都已经安装了git，安装方法忽略。验证是否已经安装：

git --version

服务器端建立裸仓

这里的示例是在当前用户的目录下建立zimohan.com.git的裸仓。

cd ~/
git init zimohan.com.git --bare

配置githooks

进入hooks目录并新建post-receive文件，意思是在git receive到信息之后运行该文件中的命令。

cd ~/zimohan.com.git/hooks/
sudo vi post-receive

并粘贴入以下内容：

#!/bin/bash
sudo git --work-tree=/file/local/zimohan.com --git-dir=/file/local/zimohan.com.git checkout -f
sudo mkdocs build -f /file/local/zimohan.com/mkdocs.yml -d /var/www/zimohan.com/

- --work-tree=后面跟的服务器端的mkdocs项目所在的路径。我这里是：/home/username/zimohan.com。 - --git-dir=后面跟的是服务器端所建立的裸仓的路径。我这里是：/home/username/zimohan.com.git。 - -f后面跟的是mkdocs的配置文件mkdocs.yml的路径。我这里是：/home/username/zimohan.com/mkdocs.yml。 - -d是将生成的静态文件的存放路径，也就是nginx配置的域名中所指定的文件存放目录。我这里是：/var/www/zimohan.com/ 。

以上命令大概是这么个意思：当有新的内容通过git提交时，git-dir后面的git仓内容导出到work-tree所在文件夹（远程mkdocs所在的文件夹），然后让mkdocs执行build命令生成静态文件到nginx配置的域名的文件存放目录。
然后赋予post-receive可执行权限：

sudo chmod +x post-receive

本地克隆服务器的裸仓

本地电脑克隆服务器端建立的裸仓

git clone username@zimohan.com:/file/local/zimohan.com.git

- username是ssh登录的用户名。 - /file/local/zimohan.com.git是前面提到的服务器端建立的裸仓的路径。我这里是：/home/username/zimohan.com.git 。
完成操作后，本地电脑的当前路径下将会出现一个名称为zimohan.com的文件夹，该文件夹就是从服务器克隆下来zimohan.com.git裸仓。

实现自动发布

本地修改文档

将本地mkdocs项目中的文件全部复制到克隆到本地的文件夹中（zimohan.com），当然，也可以重新新建个mkdocs的项目存放到此文件夹中。根据你自己的情况选择吧。但是，以后mkdocs项目的工作目录就一定要切换到这个文件夹。也就是说，以后增、删或者是修改文档，都在这个文件夹内操作。

Git操作

如果你还不会git的一些操作，也完全不用担心，本节将讲解一些基本操作。

一、切换工作目录

当mkdocs文档做了更改后，切换到本地mkdocs的工作目录（根据你个人的情况）：

cd ~/zimohan.com

- cd ~/zimohan.com是本地mkdocs所在目录。

二、提交更改

如果只是修改了文档，那么只需要：

git commit -am "des"

- des替换为你本次更改的描述信息，比如:添加xx文章，修改xx文章等待。
如果是新增了文档，那么在上一步之前，还需要执行：

git add "docs/xx.md"

- docs/xx.md替换为你新增的文章的具体md文件。注意区分路径。

三、推送更新到服务器端

git push

浏览器访问你的域名，是不是已经能够看见变化了呢？（由于浏览器缓存的缘故，可能需要强制刷新一次，或者换个未曾访问过该域名的浏览器试试）