MkDocs实现自动发布静态网站

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

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

本教程的各个硬件如下

服务器端安装并配置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的版本号并验证是否安装:

python -V

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

安装pip

最新的python安装时,会自动安装上pip。但是gec版的Ubuntu没有安装,需要自行安装。这里使用第三方的脚本来安装最新的版本。

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

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

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项目。我这里放在当前用户目录下:

cd ~/
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/

以上命令大概是这么个意思:当有新的内容通过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

实现自动发布

本地修改文档

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

Git操作

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

一、切换工作目录

当mkdocs文档做了更改后,切换到本地mkdocs的工作目录(根据你个人的情况):

cd ~/zimohan.com

二、提交更改

如果只是修改了文档,那么只需要:

git commit -am "des"
git add "docs/xx.md"

三、推送更新到服务器端

git push

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


发表于:2019-6-15
更新于:2019-6-15