基于Hugo的博客搭建指南

2020-11-27 约 3296 字预计阅读 7 分钟次阅读

下载安装包

从 https://github.com/gohugoio/hugo/releases 下载extended版本的Windows-64bit.zip到某个目录，如D:\Hugo，解压后，将该目录添加到Windows的PATH环境变量。

打开cmd，输入hugo version验证安装是否成功，有显示版本即可。

同时，最好安装上Go和git。

建立新网站

进入一个磁盘用于存放博客文件，如D:\。然后在该文件夹右键Git Bash Here（当然用cmd也可以），打开命令行键入如下命令。

1
2
hugo new site blog
“blog”可定义为自己喜欢的名字

该代码将在D盘创建一个名为blog的文件夹并在里面创建一个新的Hugo网站。当前，站点的目录如下：

1
2
3
4
5
6
7
archetypes/ #存放创建md文件时使用的模版，可定制
content/    #存放各种展示给访客的md文件，该目录下课创建多个子目录来进行分类，每个子目录是一个section
data/		#存放定义变量的模版文件
layouts/	#存放渲染html的模版文件
static/		#存放静态内容，如图片等
themes/		#存放原始主题文件，没有必要的情况下不要改动里面文件
config.toml	#主题配置文件

添加主题

接下来就是激动人心的选主题时刻了，可以去 https://themes.gohugo.io/ 选一款自己比较喜欢的主题作为初始的主题，之后再补充里面的细节。

推荐几款比较不错的主题：LeaveIt，MemE，even，LoveIt，Academic

从GitHub下载主题并将其添加到站点的themes目录中，此处以LoveIt主题为例：

1
2
3
cd blog
git init
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt

然后将主题添加到站点配置中，在config.toml中添加

1
theme = "LoveIt"

然后，在前往主题配置网站的SiteConfiguration复制其余站点配置到config.toml中。

添加内容

新建一篇文章：

1
hugo new "posts/hello-world.md"

新建一个关于页面：

1
hugo new "about/_index.md"

可以看到在~blog\content下会产生posts和about两个文件夹，里面各有一个markdown文件，把里面的draft:true删除。

启动服务器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
hugo server
hugo server后可加的常用参数
--bind="127.0.0.1"    			服务监听IP地址；
-p, --port=1313       			服务监听端口；
-w, --watch[=true]      		监听站点目录，发现文件变更自动编译；
-D, --buildDrafts     			包括被标记为draft的文章；
-E, --buildExpired    			包括已过期的文章；
-F, --buildFuture     			包括将在未来发布的文章；
-b, --baseURL="www.example.com"  服务监听域名；
--log[=false]:           		开启日志；
--logFile="/var/log/hugo.log":  log输出路径；
-t, --theme=""          		指定主题；

打开浏览器跳转http://localhost:1313即可看到渲染的界面，在命令行按ctrl+c结束。

托管到GitHub Page

创建一个仓库，命名为<YOUR-PROJECT>（例如blog）。这是将包含博客源文件的仓库，这个仓库可以是Private/Public。
创建一个仓库，命名为<USERNAME>.github.io。这是用于部署博客的仓库，且该仓库必须是Public的。这是通过main分支来启用GitHub Page的方式，只允许一个仓库通过main分支来启用GitHub Pages。配置好后通过直接访问https://<USERNAME>.github.io/，即可看到个人站点。
此外，如果有其他仓库需要使用GitHub Page，则需要给仓库创建一个名为gh-pages的分支，然后把该分支设为source分支即可。

配置公钥和私钥到仓库。这一步是为了使用Git Action自动构建，自动部署，每次只需上传源文件到<YOUR-PROJECT>仓库即会自动部署到<USERNAME>.github.io仓库。首先在本地博客根目录打开Git Bash，输入以下命令生产密钥对。

1
2
3
# 修改 username 为你自己的 GitHub 用户名
ssh-keygen -t rsa -b 4096 -C "username@users.noreply.github.com"
# 注意：这次不要直接回车，以免覆盖之前生成的,改个名字即可

将生成的密钥对分别添加到：

公钥(.pub后缀，如id_rsa.pub)
前往<USERNAME>.github.io，Settings > Deploy keys > Add deploy key，复制到对应框中。
名字随意，但务必勾选Allow write access。
私钥(无后缀，如id_rsa)
前往<YOUR-PROJECT>仓库，Settings > Secrets > New secret，复制到对应框中。
此时名字必须为DEPLOY_KEY，这是为了与后面的Action脚本里环境变量名字对应。

在本地博客根目录下创建.github/workflows/build.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
# .github/workflows/build.yml
    
name: CI #自动化的名称
on:
  push: # push的时候触发
    branches: # 那些分支需要触发
      - main
jobs:
  build:
    runs-on: ubuntu-latest # 镜像市场
    steps:
      - name: checkout # 步骤的名称
        uses: actions/checkout@v2.3.4 #软件市场的名称
        with: # 参数
          submodules: true
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2.4.13
        with:
          hugo-version: '0.78.1' #填写本地使用的Hugo版本
          extended: true
      - name: Build
        run: hugo --minify
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v2.5.1
        env:
          ACTIONS_DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          EXTERNAL_REPOSITORY: username/username.github.io
          PUBLISH_BRANCH: main
          PUBLISH_DIR: ./public

这里需要改四处地方：

Line7，填写放置源文件仓库的分支。
Line19，hugo-version填写本地使用的Hugo版本。
Line27，EXTERNAL_REPOSITORY填写部署GitHub Pages的仓库。
Line28，PUBLISH_BRANCH填写部署GitHub Pages仓库的分支。

创建一个.gitignore文件，并在其中添加下面的内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
### Hugo ###
# Generated files by hugo
/resources/_gen/
.env
public/
# /themes/
    
# Executable may be added to repository
hugo.exe
hugo.darwin
hugo.linux
    
# OSX
.DS_Store

绑定存放源文件的远程仓库

1
git remote add origin git@github.com:username/<YOUR-PROJECT>.git

使用脚本自动上传。创建一个upload.sh脚本，用chmod +x upload.sh将其设为可执行文件。

首次上传建议将以下脚本手动输入一次，特别是第13行应换成git push -u origin main，跟之后的上传有略微区别。如果不让push，先使用git pull再push即可。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
#!/bin/sh
# If a command fails then the update stops
set -e
    
git add .
# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
    msg="$*"
fi
git commit -m "$msg"
    
git push

此后使用./upload.sh "Your optional commit message"便会提交源文件到<YOUR-PROJECT>上。在该仓库的Actions处可以看到部署进度，大约等一分钟Action运行成功后，从浏览器访问https://<USERNAME>.github.io便可以查看博客内容了。

添加域名

不同域名服务商略有区别，但原理是一样的，从国外域名服务商购买域名配置简单些。

购买域名后，找到配置DNS的界面，添加几条A记录和CNAME记录：

Type	Host	Value
A	@	185.199.108.153
A	@	185.199.109.153
A	@	185.199.110.153
A	@	185.199.111.153
CNAME	www	username.github.io

在本地博客的static目录下创建名为CNAME的文件，里面填入域名，如xxx.com。

接下来去GitHub配置，在<USERNAME>.github.io仓库点击Settings > Options，下拉找到：

在Custom domain填入注册的域名后，等待一段时间生成证书，然后勾选Enforce HTTPS，进度会在上方显示(Your site is published at xxx那里)。部署成功的图如上所示。同时，可以发现在该仓库多了一个名为CNAME的文件，里面记录的就是刚刚绑定的域名，之后就可以通过该域名访问博客了。

同时部署到多个Pages服务

打开博客根目录隐藏文件夹.git下的config文件，添加url源

1
2
3
4
[remote "origin"]
	url = git@github.com:<USERNAME>/<USERNAME>.github.io.git
	url = git@e.coding.net:<USERNAME>/hugo-deploy/hugo-deploy.git #这个是添加的url源
	fetch = +refs/heads/*:refs/remotes/origin/*

此后每次执行git push origin main就会推送到多个远程库。

在新的环境继续工作

新的电脑上工作就可以把之前同步到GitHub上的博客源文件同步下来继续工作。

在安装好环境(Go+git+Hugo)后，在终端进入想要放置博客的目录，使用git命令拉去远程仓库，将submodule初始化并更新。

1
2
3
git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>
git submodule init
git submodule update

在新的环境中，两个子模块的仓库不在任何分支上，需要进入到对应的目录，然后使用git checkout main将分支切换到main上面。

1
2
3
4
cd public
git checkout main
cd ../themes/<YOURTHEME>
git checkout main

接下来就可以在新的环境继续工作了。

主题客制化

#免费图标 http://www.fontawesome.com.cn/

#压缩SVG https://jakearchibald.github.io/svgomg/

#制作图标 https://realfavicongenerator.net/