一直想写一个blog来记录自己的人生点点滴滴,之前一直忙于工作,最近稍微空闲下来了,于是开始着手这个事情。

为什么要搭建blog

  1. 对自己已经掌握的知识进行系统性地梳理、整理
  2. 分享,也许自己总结的知识正是别人需要的
  3. 记录自己的点滴,写 blog 有助于自己的思考

HUGO

HUGO是一个静态网站生成软件,用GO语言写成,据说是目前最快的静态blog生成工具了;

当然了,不仅仅是因为它快,用过Emacs的人都比较喜欢用orgmode来写文档,那么我写blog当然也想用能够支持Emacs orgmode的了,hugo现在已经提供了对Emacs orgmode的native支持;

不过后来发现hugo对Emacs orgmode还不能完全支持,不过还好还有ox-hugo,可以用来完美地将orgmode转成hugo支持的markdown格式的,很赞。

初始化blog

安装hugo

我用的是macOS,安装起来很简单

1
brew install hugo

新建blog

1
2
3
4
5
hugo new site blog
cd blog
git init
git add .
git commit -m "init project"

该命令会新建一个blog目录,并且初始化这个目录,站点所有的东西都会在这个目录下面。

选择主题

hugo thems 上面挑选一个喜欢的theme,然后安装,我选择的是 stack

1
2
3
cd blog/
git clone https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
git submodule add https://github.com/vinurs/hugo-theme-stack/ themes/hugo-theme-stack

拷贝 hugo-theme-stack 主题下面的 exampleSite 里面的内容到 blog 目录下面

1
2
rm -rf config.toml
cp -rf themes/hugo-theme-stack/exampleSite/* ./

在blog目录下面生成站点

1
2
3
4
# 生成站点
hugo
# 本地预览
hugo server

这样本地可以通过 http://localhost:1313/ 这个来进行访问了,这样一个blog的雏形就搭建好了。

执行 hugo 以后会在blog/public下面生成可以发布的站点,后面我们只要把 public 下面的内容放到我们自己的github.io上面去就可以了。

GITHUB PAGE

由于我自己从事软件开发,因此我选择了大部分程序员的方式,通过 github page 来进行搭建。

发布

在github上面新建一个 用户名.github.io 的仓库,clone到本地,然后将我们上面的 public 里面的内容copy到这个仓库下面就可以了,最后再push到远程仓库。

1
2
3
4
5
6
git clone https://github.com/vinurs/vinurs.github.io.git
cp -rf blog/public/* vinurs.github.io/
cd vinurs.github.io
git add .
git ci -m "init the website"
git push

这时候我们就可以通过 https://vinurs.github.io 来进行访问了,第一次部署的时候可能需要等个一分钟才能访问。

自动化发布──github-actions

按照上面的发布过程,我们每次更新了文章以后都要执行上面一系列的操作,然后才能更新站点。

那么有没有一种方法能够自动执行上面的过程呢?这样我们就只需要关注写文章本身就可以了,答案就是 github actions

github page读取的是github.io的master分支,因此我们建立了一个 source 分支,clone到本地,删除掉里面的内容,然后将刚才blog目录下面的内容copy过去

1
2
3
4
5
6
7
8
git clone --branch=source https://github.com/vinurs/vinurs.github.io.git
cd vinurs.github.io
rm -rf *
git add .
git ci -m "delete published files"
git push
cd -
cp -rf blog/* vinurs.github.io

themes/hugo-theme-stack 我们是作为主题来单独维护的,因此作为一个submodule增加进去

1
2
3
4
cd vinurs.github.io
rm -rf themes
mkdir themes
git submodule add https://github.com/vinurs/hugo-theme-stack/ themes/hugo-theme-stack

public、resources里面的内容不需要提交,这个是每次自动生成的,因此我们增加了 .gitignore 文件来忽略这两个目录

ACTIONS_DEPLOY_KEY

想通过github来自动发布我们需要建立 ACTIONS_DEPLOY_KEY

生成一对 ssh key

1
ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""

将会得到两个文件:gh-pages.pub(公钥) 和 gh-pages(私钥),用文本编辑器打开可以看到文件的内容。 在 vinurs.github.io 项目主页中,找到 Repository Settings -> Secrets -> Actions 添加这个私钥的内容并命名为 ACTIONS_DEPLOY_KEY

vinurs.github.io 项目主页中,找到 Repository Settings -> Secrets -> Deploy Keys -> 添加这个公钥的内容,命名为 ACTIONS_DEPLOY_KEY ,并勾选 Allow write access

增加github workflows

参照这里的配置说明:https://github.com/peaceiris/actions-hugo

在项目的根目录下面新建对应的目录以及文件:

1
2
mkdir -p .github/workflows/
touch .github/workflows/main.yml

main.yml里面的文件内容如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
name: github pages

on:
  push:
    branches:
    - source

jobs:
  build-deploy:
    runs-on: ubuntu-18.04

    steps:
    - uses: actions/[email protected]
    - name: Checkout submodules
      shell: bash
      run: |
        auth_header="$(git config --local --get http.https://github.com/.extraheader)"
        git submodule sync --recursive
        git -c "http.extraheader=$auth_header" -c protocol.version=2 submodule update --init --force --recursive --depth=1        

    - name: Setup Hugo
      uses: peaceiris/[email protected]
      with:
        hugo-version: 'latest'
        extended: true

    - name: Build
      run: hugo --gc --minify --cleanDestinationDir

    - name: Deploy
      uses: peaceiris/[email protected]
      with:
        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        publish_dir: ./public
        publish_branch: main # deploying branch

然后将刚才的内容推送到source分支上面去就可以了,我们可以通过 https://github.com/vinurs/vinurs.github.io/actions 这个页面来查看这个action执行的结果,一般是没什么问题的,有问题的话就google解决一下就可以,基本不会出现什么问题。

绑定自己的域名

github域名设定就是在根目录下面建一个 CNAME 文件,在hugo里面,我们只需要将原来的 CNAME 文件存放到 static 目录下面即可。

重新 clone

上面的是建立的过程,然后我们需要重新 clone 一下

1
git clone --recurse-submodules --branch=source https://github.com/vinurs/vinurs.github.io.git

更新历史

  • 2020-12-22
    • 初稿