目录

Hugo系列(1) - 简单搭建教程与远程部署

前言

使用Hexo搭建个人博客也有两年多时间了,当文章数量达到上百篇之后,开始发现Hexo生成文章的效率越来越慢,直到每次生成都需要至少五分钟的时间。我发现生成效率和文章涉及到的分类和标签有很大关系,由于文章数量多,每篇文章又都关联了若干个分类和标签,再加上我使用了压缩样式的插件,最终导致极其低下的生成效率。

在经过一段时间的考量后,决定将Hexo博客迁移到Hugo。Hugo是用go语言开发的,在用法上和Hexo类似,可以简单地把Hugo当成go语言版的Hexo,但是它拥有更快的生成效率。下面是官网的原话:

The world’s fastest framework for building websites

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

安装

和Hexo不同,Hugo安装非常简单,只需要去Hugo Release下载操作系统对应的二进制文件即可(hugo或者hugo.exe)。

对于Windows平台,一般是一个zip文件,解压后里面有个hugo.exe文件。将该文件所在目录添加到环境变量path里,即可在cmd里通过hugo version检测是否能正常运行hugo命令。

如下是我安装的hugo版本:

1
2
>hugo version
Hugo Static Site Generator v0.74.2/extended windows/amd64 BuildDate: unknown

其他平台的安装方法可以参考官方文档:Install Hugo

创建站点

首先需要创建一个新的个人站点:

1
hugo new site blog

blog就是你的博客站点所在的目录,也是这个站点的根目录,创建站点后目录结构如下:

1
2
3
4
5
6
7
archetypes/
content/
data/
layouts/
static/
themes/
config.toml

下面简单介绍下Hugo根目录下的各个文件目录的作用:

  • archetypes存放创建文件时使用的模板,可以自定义front matter属性。
  • assets存放需要被Hugo Pipes处理的文件,且只有使用了.Permalink或者.RelPermalink的文件才能被发布到public目录。 注意,默认不会创建assets目录。
  • config是配置文件,可以有JSONYAML或者TOML三种格式,默认使用根目录下的config.tomlconfig.yamlconfig.json中的某一个。可以通过--config来配置读取一个或多个配置文件,如:hugo --config a.toml,b.toml,c.toml注意,默认不会创建config目录。
  • content存放的各种md文件用于部署站点,该目录下可以自行创建若干个子目录来便于对文章进行分类,这些子目录被称为section
  • data目录存放的是用于定义变量的模板文件,相当于Java里的常量类,这些文件有JSONYAML或者TOML三种格式,会在生成站点时被使用到。一般用不到该功能,具体用法可以参考:data templates
  • layouts目录存放的模板文件用于渲染html页面,模板里可以定义不同页面的html代码。
  • static目录存放的是静态内容:图片、CSS、JavaScript等。
  • resources目录用于缓存某些文件来提高生成效率。 注意,默认不会创建resources目录。

添加主题

为新站点添加一个主题,以我使用的LoveIt主题为例,先将主题代码放置到themes目录下:

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

接着修改config.toml

1
theme = "LoveIt"

这里的LoveIt对应themes目录下的主题的文件夹名字。

新建文章

新建一篇文章:

1
hugo new posts/first.md

该命令会在content/posts目录下生成first.md文件,打开进行编辑:

1
2
3
4
5
6
7
8
---
title: "First"
date: 2020-09-08T21:57:28+08:00
draft: true
---
## First

First blog.

两行---里的属性是front matter,用来设置当前文章的属性配置。front matter的内容可以使用3种不同的格式来定义,两行---之间对应的是YAML格式,两行+++之间对应的是TOML格式,{}之间对应的是JSON格式。

建议用YAML格式来定义,这样从Hexo迁移到Hugo的成本会更低。

下面是官方文档提供的3种不同格式的front matter的样例,有兴趣的可以了解下。

TOML Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
+++
title = "spf13-vim 3.0 release and new website"
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
date = "2012-04-06"
categories = [
  "Development",
  "VIM"
]
slug = "spf13-vim-3-0-release-and-new-website"
+++
Content of the file goes Here

YAML Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
---
title: "spf13-vim 3.0 release and new website"
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
lastmod: 2015-12-23
date: "2012-04-06"
categories:
  - "Development"
  - "VIM"
slug: "spf13-vim-3-0-release-and-new-website"
---

Content of the file goes Here

JSON Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "title": "spf13-vim 3.0 release and new website",
    "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
    "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
    "date": "2012-04-06",
    "categories": [
        "Development",
        "VIM"
    ],
    "slug": "spf13-vim-3-0-release-and-new-website",
}

Content of the file goes Here

启动Hugo服务

输入命令:

1
hugo server -D

在本地启动服务后可以在 http://localhost:1313/ 访问个人站点。该命令仅用于本地调试,支持热修改,也就是说在启动服务时修改文章会实时生效,但是该命令不会真正生成静态文件。

生成静态页面

输入命令:

1
hugo -D

默认会在站点根目录的public/目录下生成对应的静态页面,可以通过在命令行指定-d或者--destination参数来改变静态页面的存放路径,也可以通过在配置文件中设置publishDir来指定。

该命令生成的静态页面文件是用来部署到pages服务的,比如GitHub pages或者Coding pages等。

另外,hugo允许对生成的静态页面设置特殊的参数,比如在文章的front matter里设置参数:draft, publishdateexpirydate。如下:

1
2
3
4
5
6
7
---
title: "First"
date: 2020-09-08T21:57:28+08:00
draft: true
publishdate: 2020-09-18T21:57:28+08:00
expirydate: 2020-09-28T21:57:28+08:00
---

draft: true表明该文章是草稿,如果在启用服务时不指定参数-D--buildDrafts,或者在配置文件config.toml中配置buildDrafts = true,则会在生成文章时忽略草稿。如果不想指定该参数就生成文章,需要改为draft: false或者将其删去。

publishdate: 2020-09-18T21:57:28+08:00表示将来发布的时间,如果不指定参数-F--buildFuture,或者在配置文件config.toml中配置buildFuture = true,则无法在规定的日期之前生成该文章。

expirydate: 2020-09-28T21:57:28+08:00表示过期时间,如果不指定参数-E--buildExpired,或者在配置文件config.toml中配置buildExpired = true,则无法在规定的日期之后生成该文章。

远程部署到Pages服务

Hugo和Hexo一样是静态站点生成工具,不需要服务器即可进行部署运行,为了可以在网络上也访问到我们的博客,需要将静态博客部署到某些网站的pages服务上,借用人家的服务器进行托管。

常用的Pages服务有GitHub pages、Coding pages等,由于暂时没有找到好用的Hugo的远程部署插件,所以这里使用Git命令来进行远程部署。

注意,所谓的远程部署,其实就是把hugo命令生成的public目录里的所有文件push到远程库,然后启用Pages服务进行静态网站的部署。这样,当有人访问静态站点的主页时,Pages服务就会去读取根目录下的index.html

本文以部署到GitHub Pages为例。

安装Git

首先要安装Git,Git是一个版本控制工具,可以用来帮忙管理我们的博客,直接前往官网下载安装包即可。

下载链接

在安装的时候会问你是否安装git的cmd工具,把这个也一起安装了后就可以不需要配置环境变量了。这样就可以直接在cmd窗口里运行Git命令,如git version

当然也可以直接使用安装时自带的Git Bash,个人更喜欢用Git Bash。

在GitHub上创建一个仓库

首先在GitHub上创建一个仓库,仓库的名字格式为<username>.github.io。比如我的GitHub用户名是lewky,那么这个仓库就命名为lewky.github.io

之所以这样规定命名,是因为GitHub默认会把<username>.github.io的master分支的内容部署到GitHub Pages站点上。

SSH key的创建与配置

因为要使用SSH的方式来和GitHub仓库进行交互,我们需要生成一对密钥对,然后将公钥配置到GitHub账号上。关于SSH key的创建与配置到GitHub,可以看我的另一篇文章的一个小章节:#四、SSH key的创建与配置 的4.1 ~ 4.3的部分。

在本地关联GitHub的站点仓库

在本地创建一个新的文件夹,比如名为hugo-deploy。首先是初始化该文件夹为Git项目,命令如下:

1
git init

然后把本地的Hugo博客通过hugo命令生成的public目录下的所有文件都复制到这个新建的文件夹hugo-deploy里,然后用Git命令把这些复制过来的文件添加到本地仓库:

1
git add .

接着是提交修改,命令如下:

1
git commit -m "第一次提交"

-m参数代表提交信息,用于说明本次提交的目的,比如你发布了什么文章、修改了什么样式之类的信息说明。该参数不可以省略,不然会报错,另外要注意这里的双引号是英文的双引号

接着把刚刚在GitHub上创建的仓库的SSH地址复制下来:点击GitHub仓库的Code绿色按钮,点击SSH就可以看到该仓库的SSH地址,然后点击地址后面的复制按钮即可。

用Git命令把这个SSH地址添加到我们的本地仓库,这样这个GitHub仓库就将作为我们的远程仓库,然后就可以通过Git命令把站点文件部署到GitHub上:

1
git remote add origin git@github.com:lewky/lewky.github.io.git

这里的origin是远程库的别名,后面是要关联的远程库SSH地址。

然后就是最后一步了,把我们刚刚提交到本地库的文件给推送到远程库。由于远程库刚刚创建,还不存在本地的分支(默认是master分支),所以第一次提交的命令要加是一个-u参数:

1
git push -u origin master

这样GitHub远程库上会创建出对应的master分支,以后推送文件的时候,就不需要再加上该参数了:

1
git push origin master

启用GitHub Pages服务

通过master分支来启用GitHub Pages

现在我们的GitHub仓库里已经有站点的文件了,接下来点击Settings进入该仓库的设置页面,找到Github Pages这一项,选择以master分支作为Source,然后保存;接下来这个仓库就会被部署到https://{username}.github.io/{仓库名}

你会发现这里的url里多了子路径,但是如果仓库名是{username}.github.io的格式,那该url就会被简化为https://{username}.github.io/,这样就不需要在url后边添加上仓库名来访问个人站点了。

通过gh-pages分支来启用GitHub Pages

还有一种启用的方式是给仓库创建一个名为gh-pages的分支,然后把该分支设置为Source,同样可以让该仓库使用到GitHub Pages服务。

这种启用方式是只有当存在多个项目都要使用GitHub Pages才使用的,因为目前GitHub只允许一个仓库可以通过master分支来启用GitHub Pages。如果其他仓库也要使用GitHub Pages,就需要创建gh-pages分支来部署。

怎么同时部署到两个不同的Pages服务

进入本地仓库的目录,打开隐藏文件夹.git下的config文件,多添加一行url = xxx,如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[core]
	repositoryformatversion = 0
	filemode = false
	bare = false
	logallrefupdates = true
	symlinks = false
	ignorecase = true
[remote "origin"]
	url = git@github.com:lewky/lewky.github.io.git
	url = git@e.coding.net:lewky/hugo-deploy/hugo-deploy.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[pull]
	rebase = true
[branch "master"]
	remote = origin
	merge = refs/heads/master

此后只需要git push origin master就可以同时推送到多个远程库。

参考链接

注意
本文最后更新于 September 6, 2020,文中内容可能已过时,请谨慎使用。