记录使用Hugo和Github Pages 搭建博客的过程和方法

Hugo介绍

Hugo是什么，下面是来自官网的介绍：

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.

Hugo是一个流行且开源的静态网站生成器。所谓静态网站就是提前生成成html页面，不需要在访问时重新计算生成， 也无需数据库参与，只需要部署即可访问，维护简单，访问速度快。Hugo读取用户编写的Markdown格式内容的文件， 和配置好的模板，生成漂亮干净的静态页面。

安装Hugo

Mac上安装Hugo

1

brew install hugo

Windows上安装Hugo

1

choco install hugo -confirm

源码安装,Hugo使用Go语言开发，所以需要安装Go

1
2
3
4
5

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install --tags extended

使用Hugo创建网站

创建一个网站，指定生成路径：/path/to/site

1

hugo new site /path/to/site

进入刚才创建的目录/path/to/site，在目录下可以看到几个目录和config.toml配置文件

1
2
3
4
5

archetypes/ 
content/
layouts/
static/
config.toml

这几个文件夹的作用分别是：

  • archetypes：包括内容类型，在创建新内容时自动生成内容的配置
  • content：包括网站内容，全部使用markdown格式
  • layouts：包括了网站的模版，决定内容如何呈现
  • static：包括了css, js, fonts, media等，决定网站的外观

添加网站主题

Hugo提供许多不同风格的网站主题themes.gohugo.io，可以为网站选择一个主题， 下载这些主题，将主题放在themes/目录下

1

$ git clone --recursive https://github.com/spf13/hugoThemes themes

比如本站选择的主题even

1

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

修改config.toml，添加主题配置如下：

1

theme = "even"

添加网站页面

为网站添加一个页面

1

$ hugo new about.md

在content/目录下自动生成一个Markdown格式的名为about.md的文件。其内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ cat content/about.md
---
title: "About"
date: 2020-08-02T10:56:25+08:00
draft: false
lastmod: 2020-08-02T11:00:24+08:00
menu: "main"
weight: 50

---

使用hugo new命令生成的文件前面自动生成的几行，是用来设置文章属性的，这些属性使用的是yaml语法。

  • date 自动增加时间标签，页面上默认显示n篇最新的文章。
  • draft 设置为false的时候会被编译为HTML，true则不会编译和发表，在本地修改文章时候用true。
  • title 设置文章标题
  • tags 数组，可以设置多个标签，都好隔开，hugo会自动在你博客主页下生成标签的子URL，通过这个URL可以看到所有具有该标签的文章。
  • categories 文章分类，跟Tag功能差不多，只能设置一个字符串。

运行网站服务器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

$ hugo server -D
                   | EN
-------------------+------
  Pages            | 269
  Paginator pages  |  29
  Non-page files   |   0
  Static files     | 100
  Processed images |   0
  Aliases          |  56
  Sitemaps         |   1
  Cleaned          |   0

Built in 1054 ms
Watching for changes in /Users/piao/data/golang/src/gitee.com/piao/piao.gitee.io/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /Users/piao/data/golang/src/gitee.com/piao/piao.gitee.io/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

运行成功后，在浏览器中输入地址http://localhost:1313/即可访问网站。

在当前目录下多了一个文件夹public/，这里面是Hugo生成的整个静态网站。

部署到github pages

如果使用Github pages来作为博客的Host，只需要将public/里的文件上传就可以，这相当于是Hugo的输出。

在github上创建的仓库名需要和用户名一致，访问地址才是：https://用户名.github.io/ 否则访问地址就是：https://用户名.github.io/仓库名/ 登录github/仓库名/进入项目pages页面手动更新，gitee自动更新收费,github不收

推送到github

1
2
3
4
5
6

cd public
git init
git remote add origin https://github.com/piaohua/piaohua.github.io.git
git add -A
git commit -m "first commit"
git push -u origin master

关于本站

本站使用命令hugo new deploy.sh创建部署脚本，将部分操作集成在脚本内，deploy.sh。

本站同时推送到github和gitee，所以使用两份配置，生成静态文件在不同的位置。

详细配置见文档https://gitee.com/piao/piao.gitee.io

网站评论插件gitalk

配置gitalk评论插件

1
2
3
4
5
6

  [params.gitalk]           # Gitalk is a comment system based on GitHub issues. see https://github.com/gitalk/gitalk
    owner = ""              # Your GitHub ID
    repo = ""               # The repo to store comments
    clientId = ""           # Your client ID
    clientSecret = ""       # Your client secret

Gitalk评论插件需要在Github上为项目生成密钥，且要为每个业务创建评论的Issue，为Issue添加固定的labels。

比如本站为About页面创建的Issue及Lables。

http://github.com/piaohua/piaohua.github.io/issues/2

设置的lables必须和页面中的Gitalk的id一致，否则无法获取到内容，gitalk的id在themes/even/layouts/partials/comments.html中，内容如下，可以修改id为页面路径location.pathname

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

      var gitalk = new Gitalk({
        id: '{{ .Date }}',
        title: '{{ .Title }}',
        clientID: '{{ .Site.Params.gitalk.clientId }}',
        clientSecret: '{{ .Site.Params.gitalk.clientSecret }}',
        repo: '{{ .Site.Params.gitalk.repo }}',
        owner: '{{ .Site.Params.gitalk.owner }}',
        admin: ['{{ .Site.Params.gitalk.owner }}'],
        body: decodeURI(location.href)
      });

抓取获取issue内容的请求地址如下,可以发现地址参数中的lables： https://api.github.com/repos/piaohua/piaohua.github.io/issues?labels=Gitalk,2020-08-02+10:56:25+%2B0800+CST&t=1659787492587

使用页面路径作为id，获取地址lables参数为`/about/： https://api.github.com/repos/piaohua/piaohua.github.io/issues?labels=Gitalk,%2Fabout%2F&t=1659789016548

详细操作文档见Gitalk 评论插件使用指南

Gitee可以使用第三方应用

网站评论插件giscus

gitalk需要为每个页面创建评论的Issue，使用起来比较麻烦，[giscus]受 utterances 的启发,

giscus是由 GitHub Discussions 驱动的评论系统。

  1. Enabling GitHub Discussions on your repository

在自己的 github pages 项目下开启 Discussions 功能。

  1. 安装 giscus app

打开 giscus, 点击安装即可。

  1. 启用 giscus

打开 giscus

打开后，在 仓库：填写自己的仓库，格式：用户名/仓库名，比如：piaohua/piaohua.github.io

Discussion 分类，选择 announcements

页面 ↔️ discussion 映射关系、特性、主题 可以使用默认选择

完成后，会生成 <script> 标签，示例如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<script src="https://giscus.app/client.js"
        data-repo="piaohua/piaohua.github.io"
        data-repo-id="MDEwOlJlcG9zaXRvcnkyODQ0MjQ4NDM="
        data-category="Announcements"
        data-category-id="DIC_kwDOEPP6i84ChN9S"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

然后将上面 <script> 标签嵌入到项目的评论页面中，

比如当前项目模板是hugo-theme-even，在themes/evenlayouts/partials/comments.html中添加即可。

然后就可以在博客文章中评论。

参考