GitHub+Hugo搭建个人博客

GitHub仓库创建

GitHub Pages 是通过 GitHub 托管和发布的公共网页，首先需要创建一个名为username.github.io的仓库， username是Github的账户名。

注意：如果设置为xxx.github.io跟username不一致，将无法通过https://username.github.io/访问。

Hugo安装

Hugo是一个静态网站生成工具，可以将markdown内容自动转换为静态网页，相比其他生成工具，Hugo主要有以下优点：

依赖少、使用简单、部署方便
极快的页面编译生成速度
内置web服务器，方便本地调试
完全跨平台支持

参考Hugo官网进行安装：https://gohugo.io/getting-started/installing/，mac上直接执行：

1

brew install hugo

在本地环境中，执行以下命令生成保存网站内容的文件夹：

1

hugo new site mysite

生成的目录结构为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


➜  mysite tree -L 1
.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── resources
├── static
└── themes

其中config.toml是hugo的配置文件，后面需要将hugo主题中的config.toml替换到本地。

Hugo使用命令hugo new file来创建新文档，并保存到content目录下，file推荐保存在content下的post子目录中：

1

hugo new post/hugo_blog.md

主题设置

Hugo有挺多开源主题，这篇文章列出了使用较多的主题：https://www.andbible.com/post/hugo-theme-review-loveit-papermond-others/。

我这里使用的是：https://github.com/olOwOlo/hugo-theme-even，按照说明安装到本地：

1

$ git clone https://github.com/olOwOlo/hugo-theme-even themes/even

然后将github示例里面的 config.toml 内容拷贝到本地 config.toml 中。

博客编写

对于上面创建的content/post/hugo_blog.md文件，使用任意编辑器即可编写内容，这里推荐使用vscode安装Office Viewer插件来编写。

Office Viewer的markdown编辑跟typora类似，集成Vditor来支持的，也是所见即所得的markdown编辑器，是typora开源替代，直接在扩展里面安装即可，文档参考：https://github.com/cweijan/vscode-office。

为了避免程序崩溃或者其他原因导致的编辑内容没有保存的尴尬场景，推荐vscode开启自动保存。vscode中打开Code(mac)/文件(windows)->首选项->设置->搜索auto save，将“Files：Auto Save”设置为afterDelay，“Files：Auto Save Delay”为自动保存的间隔时间，在afterDelay方式时才生效，默认为1秒。

同时，为了避免本地目录被意外删除的情况，推荐将mysite文件夹，存放在github私人仓库中，并且在gitignore中忽略public文件夹，这样就将文档和网页分开存储在两个仓库了。同时，可以将博客保存在云笔记进行再次备份。

本地测试

在hugo_blog.md中编辑内容后，执行命令 hugo server –buildDrafts来本地查看效果：http://localhost:1313/。

博客发布

需要先修改config.toml配置，将其中的gitRepo配置项修改为username.github.io仓库的地址，然后依次执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


hugo --buildDrafts --baseUrl="https://username.github.io/"
cd public
git init
// 如果有多个git环境（公司内部和github等），为public文件夹设置独立的用户名和邮件
git config user.name username
git config user.email test@gmail.com
git remote add origin git@github.com:username/username.github.io.git
git add -A
git commit -m ""
git push origin master

在推送博客内容到此仓库后即可生效，也有可能需要进行设置才能生效，具体参考官方文档。

格式优化

以上都是使用hugo-theme-even 默认配置生成的，很多地方可以优化，后续使用中在陆续更新。

图片路径问题

在刚开始，直接使用的Office Viewer 里的选项“上传图片或文件"，手动点击选择图片来编辑的，在vscode里面确实是有显示的，但是用Hugo无论是本地调试，还是上传到github后，都无法显示。

经过查找，找到这篇关于图片插入问题的文档，才重新梳理了下思路：

Office Viewer手动插入后：markdown里面链接地址为 image/hugo_blog/xxx.png，实际存储路径为 content/post/image/hugo_blog/xxx.png，即会文档当前目录下的image文件夹下，创建与文档同名的文件夹，然后把图片放在里面

而Hugo生成public文件夹时，对post和static文件夹处理逻辑分别是：

post文件夹处理逻辑：
- post下的xxx.md文档，会转换为index.html放到public/post/xxx文件夹下，名称和文档名一致
- post下的文件夹和图片，会复制到public/post文件夹下
static文件夹处理逻辑：将static下资源放到public跟目录下

因此对于文档hugo_blog.md，存放图片的解决办有：

放在post文件夹：图片存放位置为post/hugo_blog/1.png，markdown引用为
放在static文件夹：图片存放位置为static/image/hugo_blog/1.png，markdown引用为

至于Office Viewer插件中手动选择图片，生成后图片位置在public/post/image/hugo_blog/xxx.png，文档在public/post/hugo_blog下面，因此用image/hugo_blog/xxx.png无法找到。为了存储图片统一管理，推荐第二种方式，统一存储在static文件夹。

utterances 评论系统

安装App：https://github.com/apps/utterances
在config.toml 里配置，even主题本身已经支持，只需要配置即可

1
2
3


  [params.utterances]
    owner = "yefengzhichen"              # github id
    repo = "yefengzhichen.github.io"     # 存储评论的仓库，用配置github Pages使用的仓库即可

文章目录