记录使用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

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

参考