跳转至

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。

1
sudo apt install mkdocs

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

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

手动安装

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

安装python

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

1
python3 -V
但是,其包管理器pip则未必安装。

安装pip

检查是否已经安装:

1
pip3 -V
已经安装的话,更新下:
1
pip3 install --upgrade pip
最新的python安装时,会自动安装上pip。如果没有安装的话,需要自行安装。这里使用第三方的脚本来安装最新的版本。

1
2
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版本中。

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

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

安装mkdocs

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

1
sudo pip install mkdocs
同样的,查看下版本号,并验证安装是否成功:
1
mkdocs -V
1
mkdocs, version 1.0.4 from /usr/local/lib/python2.7/dist-packages/mkdocs (Python 2.7)

新建mkdocs项目(仅服务器端)

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

1
2
3
mkdir /home/mkdocs
cd /home/mkdocs
sudo mkdocs new zimohan.com
其中的zimohan.com是新建项目的名称,将会在当前目录中新建一个以该名称命名的文件夹,为方便区分,建议命名为网站的域名。

安装并配置Git

安装git

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

1
git --version

服务器端建立裸仓

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

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

配置githooks

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

1
2
cd ~/zimohan.com.git/hooks/
sudo vi post-receive
并粘贴入以下内容:
1
2
3
#!/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可执行权限:

1
sudo chmod +x post-receive

本地克隆服务器的裸仓

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

1
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的工作目录(根据你个人的情况):

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

二、提交更改

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

1
git commit -am "des"
- des替换为你本次更改的描述信息,比如:添加xx文章,修改xx文章等待。
如果是新增了文档,那么在上一步之前,还需要执行:
1
git add "docs/xx.md"
- docs/xx.md替换为你新增的文章的具体md文件。注意区分路径。

三、推送更新到服务器端

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