我以前一直用hexo配合github来搭建blog,当我遇到了hugo之后我立马从hexo转移到了hugo。

为什么选择hugo

HUGO是一个静态网站生成软件,用GO语言写成,据说是目前最快的静态blog生成软件了。当然了,不仅仅是因为它快,用过Emacs的人都比较喜欢用orgmode来写文档,那么我写blog当然也想用能够支持Emacs orgmode的了,hugo现在已经提供了对Emacs orgmode的native支持,而且原来的hexo的hexo-renderer-orgmode那个插件的作者也不维护了,因此就换到了hugo。

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

安装、配置hugo

安装hugo

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

1
brew install hugo

初始化blog

1
hugo new site website

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

配置theme

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

1
2
3
4
cd website
mkdir themes
cd themes
git clone https://github.com/olOwOlo/hugo-theme-even.git even

打开website/config.toml设置里面的主题名称:

1
theme = "even"

参考Even配置进行配置。

merge主题

因为考虑到以后我会对Even做一些修改,因此我fork了这个项目,上面clone的也是我自己的github上面的地址,后面定期对这个主题进行merge就可以了。

1
2
3
4
cd website/themes/even/
git remote add upstream https://github.com/olOwOlo/hugo-theme-even.git
git fetch upstream
git merge upstream/master

如果有冲突,那么就手动解决冲突问题,这个冲突一般都好解决,一般改动量不会很大。

编译主题

如果你更改了 src 目录下的任意文件,你需要重新编译它们。

1
2
3
4
5
cd ./themes/even/
# install dependencies
yarn install
# build
yarn build

在这一步的时候,最好把主题目录下面的node_modules以及yarn.lock删除掉,要不然编译很可能会报一些莫名其妙的错误。

简单使用

1
2
3
4
# 新建文章
hugo new post/hello.md
# 预览website
hugo server -D

hugo site目录结构

会自动生成这样一个目录结构:

1
2
3
4
5
6
7
8
[website]
|__ [archetypes]
| |__ default.md
|__ content
| |__ post
|__ layouts
|__ static
|__ config.toml

archetypes

用来存放新建文章的模板,hugo默认使用的是Markdown格式的,但是我比较喜欢用Emacs orgmode,因此,我们可以在archtypes下面新建default.org模板,以后我们新建的.org的文章就会基于这个模板而生成。

content

直接在这个下面新建一个文件就是固定的page,例如"关于我"的页面。

post

文章目录,我们新建的文章就会在这个目录下面。

static

用来存放website静态的文件,例如图片啊之类的,我在该目录下面新建了imgs目录,blog相关的图片就存放在这个目录下面。

config.toml

website的配置文件。

托管到github

推送到github

运行hugo server会生成一个public目录,我们只要把public目录推送到github.io上面去就可以了。

绑定自己的域名

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

自动化发布blog–travis-ci

之前,我在github上面对于我的blog建了两个仓库:

  • github.io 用来存放发布以后的页面,hugo的public里面内容就会推送到这个目录
  • website hugo所有的配置以及文章都放在这里

可以看出每次写好文章以后我就需要就执行hugo,然后将public里面的内容推送到github.io仓库里面去,虽然有一个deploy.sh脚本,但是还是觉得很麻烦,于是就有一个想法,能不能我提交到website上面的时候就自动发布到github.io上面去呢?

答案是有的,那就是利用travis-ci

现在,我们连website这个仓库都可以省略掉了,只需要一个github.io就可以了;打开github,在github.io里面新建一个分支,取名叫做source。 在本地,我们clone下source分支:

1
git clone --depth=50 --branch=source https://github.com/vinurs/vinurs.github.io.git

删除这个分支下面的所有内容:

1
rm -rf *

从原来的website目录下面,将一些文件copy到我们的新的分支目录下面:

1
cp -rf website/* vinurs.github.io/

因为主题是我fork的别人的,所以这里我们要重新设置一下主题:

1
git submodule add  https://github.com/vinurs/even.git themes/even

需要注意的是,我这里的submodule没有用git协议,是因为在travis-ci里面,他所有的操作是通过personal-key来进行了,如果这里用git的话就会失败。

准备.travis.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
languagesetup: go

go:
- 1.12.2 # 这里我原来填的是master,后来发现hugo不一定能跟最新的go兼容,因此这里指定某一个版本


install:
- mkdir $HOME/src
- cd $HOME/src
- git clone https://github.com/gohugoio/hugo.git
- cd hugo
- go install
- cd ${TRAVIS_BUILD_DIR}

script:
- hugo # This commands builds your website on travis

deploy:
local_dir: public # Default static site output dir for Hugo
repo: vinurs/vinurs.github.io # This is the slug of the repo you want to deploy your site to
target_branch: master # GitHub pages branch to deploy to (in other cases it can be gh-pages)
provider: pages
skip_cleanup: true
github_token: $GITHUB_TOKEN # This is the authentication which you will setup in the next step in travis-ci dashboard
email: [email protected]
name: vinurs
on:
branch: source

上面的install的里面的内容一定要注意,由于原来我没有写

1
- cd ${TRAVIS_BUILD_DIR}

导致一直在自动化编译不过。

将刚才所作的修改推送到source分支上去即可,travis-ci如何连接github请参考下面的链接。

参考链接

自动化发布blog–github-actions

之前我是用travis来发布,现在github支持actions了,就可以用github自带的actions来进行发布了。

参照这里的配置说明: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
36
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: master  # deploying branch

更新历史

  • 2020-04-19
    • 更新了actions-hugo以及actions-gh-pages版本
  • 2019-12-18

    • 更新了使用github actions来自动发布文章
  • 2019-06-08

    • 增加了主题编译说明
  • 2019-05-05

    • 指定了go的版本号
  • 2018-09-07

    • 更新了安装hugo的方式
  • 2017-03-13

    • 初稿