常阳时光

世界上最快静态博客生成工具 Hugo 入门折腾

Hugo 是一款开源、使用 go 语言写的静态网站生成器,很适合数据量不大的个人博客使用。(本文本地测试环境:Windows)

为什么选择 Hugo ?

网上说:快!世界上最快的静态网站生成工具!开发文档齐全!丰富的主题……不过这些都不是老杨选择 Hugo 的原因。老杨这次折腾选择 Hugo,主要是看中它基本上不用配置本地环境(Windows)。

Hugo 就一二进制执行文件(exe),下载,放至本地建站目录,执行命令就好。当然 Jekyll 托管到 GitHub 的话,本地也不用配置环境,但是 Hugo 可以很方便的在本地预览博客,测试好,再 Git 提交发布。以前折腾 Jekyll 都是本地修改文件,Git 提交,待 GitHub 端自动生成更新……(懒得配置本地环境)

安装 Hugo

Windows 安装,前往 https://github.com/gohugoio/hugo/releases 页面,下载 hugo_X.XX_Windows-64bit.zip(目前最新版本为 hugo_0.60.1_Windows-64bit.zip)。

解压得到 hugo.exe,将 hugo.exe 复制到本地建站目录,比如:D:\Hugo

Windows 用户推荐使用开源 cmderGit-bash 代替微软的 cmd.exe / Powershell,这两个工具自带了 git ssh 等常用命令,使用起来更方便。

我没有把 hugo 添加到系统环境变量。Cmder 放在 C:\Users\Administrator\Green\cmder 路径下,Hugo 在 D:\Hugo。

打开 Cmder,输入 d: 切换至 D 盘,然后 cd Hugo 进去 Hugo 工作目录(或者直接 cd /d d:/hugo)

hugo version

检查 Hugo 版本。

hugo help

获取帮助,所有命令参数。▼展开

λ hugo help                                                                                                 
hugo is the main command, used to build your Hugo site.

Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.

Complete documentation is available at http://gohugo.io/.

Usage:
hugo [flags]
hugo [command]

Available Commands:
config Print the site configuration
convert Convert your content to different formats
deploy Deploy your site to a Cloud provider.
env Print Hugo version and environment info
gen A collection of several useful generators.
help Help about any command
import Import your site from others.
list Listing out various types of content
mod Various Hugo Modules helpers.
new Create new content for your site
server A high performance webserver
version Print the version number of Hugo

Flags:
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--cleanDestinationDir remove files from destination not found in static directories
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
-c, --contentDir string filesystem path to content directory
--debug debug output
-d, --destination string filesystem path to write files to
--disableKinds strings disable different kind of pages (home, RSS etc.)
--enableGitInfo add Git revision, date and author info to the pages
-e, --environment string build environment
--forceSyncStatic copy all files when static is changed.
--gc enable to run some cleanup tasks (remove unused cache files) after the build
-h, --help help for hugo
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
--ignoreVendor ignores any _vendor directory
-l, --layoutDir string filesystem path to layout directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--minify minify any supported output format (HTML, XML etc.)
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--path-warnings print warnings on duplicate target paths etc.
--quiet build in quiet mode
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
--trace file write trace to file (not useful in general)
-v, --verbose verbose output
--verboseLog verbose logging
-w, --watch watch filesystem for changes and recreate as needed

Additional help topics:
hugo check Contains some verification checks

Use "hugo [command] --help" for more information about a command.

Hugo 建站

很简单,比如,建立一个名为 pronhub 网站:

hugo new site pronhub

因为没有把 Hugo 添加到系统环境变量,需要把 hugo.exe 复制一份到新建的 pronhub 网站目录下。新建的站点目录大概如下图,包含这些目录——D:\HUGO\PRONHUB\config.toml、hugo.exe、archetypes、content、data、layouts、static、themes

config.toml 配置

静态网站配置,config.toml 在网站根目录下,可参考一下配置(请根据实际修改)

baseURL = "https://pronhub.com/"
languageCode = "zh-CN"
title = "Pronhub"
theme = "maupassant"

## 保持分类的原始名字(false会做转小写处理)
preserveTaxonomyNames = true

## 是否禁止URL Path转小写
disablePathToLower = true

## 自动检测是否包含中文/日文/韩文,建议设置为true
hasCJKLanguage = true

## 摘要长度
summaryLength = 140

## 分页
paginate = 10
paginatePath = "page"

[author]
name = "老杨"

[params]
author = "老杨"
subtitle = "Pronhub"
keywords = "Pronhub"
description = "Pronhub"
busuanzi = true
localSearch = true

官方文档:Configure Hugo

添加一个主题

比如,添加 Maupassant 主题,网络不好,可能需要美元全局。主题添加到 themes/maupassant 目录下。

cd pronhub
git init
git submodule add https://github.com/rujews/maupassant-hugo.git themes/maupassant

编辑网站 config.toml 配置文件,启用该主题。可以在 Cmder 下直接执行命令:

echo theme = "maupassant" >> config.toml

或者直接编辑网站目录下 config.toml 文件,添加 theme = "maupassant"

Hugo 新建文章

hugo new post/pronhub.md

编辑刚才新建的 Markdown 格式文章文件 \content\post\pronhub.md,写文字,保存。比如:

---
title: "Hugo pronhub 测试文章"
date: 2019-12-06T12:19:42+08:00
lastmod: 2019-12-06T15:19:42+08:00
draft: false
description: "Hugo pronhub 测试文章"
tags: [ "pronhub" , "Hugo" ]
keywords: [ "pronhub" , "Hugo" ]
categories: [ "pronhub" ]
isCJKLanguage: true
---

Hugo pronhub 测试文章 by [常阳时光](https://cyhour.com)。

文章头部参数配置

不需要全部配置上,根据实际选择即可。

---
title: "文章标题"
description: "文章的描述信息"
tags: [ "标签1", "标签2", "标签3" ]
categories: [ "分类1", "分类2" ]
keywords: [ "Hugo", "keyword" ]
date: 2012-04-06
lastmod: 2015-12-23
# CJKLanguage: Chinese, Japanese, Korean
isCJKLanguage: true

# 如果draft为true,除非使用 --buildDrafts 参数,否则不会发布文章
draft: false

# 设置文章的过期时间,如果是已过期的文章则不会发布,除非使用 --buildExpired 参数
expiryDate: 2020-01-01

# 设置文章的发布时间,如果是未来的时间则不会发布,除非使用 --buildFuture 参数
publishDate: 2020-01-01

# 排序你的文章
weight: 40

# 使用这两个参数将会重置permalink,默认使用文件名
url:
slug:

# 别名将通过重定向实现
aliases:
- 别名1
- /posts/my-original-url/
- /2010/01/01/another-url.html

# type 与 layout 参数将会改变 Hugo 寻找该文章模板的顺序,将在下一节细述
type: review
layout: reviewarticle

# 三个比较复杂的参数
taxonomies:
linkTitle:
outputs:
# 实验性的参数
markup: "md"

# 你还可以自定义任何参数,这些参数可以在模板中使用
include_toc: true
show_comments: false
---

运行网站测试

hugo server -D

然后打开 http://localhost:1313/ 即可预览网站

这个时候修改内容,hugo 会自动重新生成网站,按 Ctrl+C 退出。

生成静态网站

发布完内容,修改好主题后,可以使用 hugo 命令生成静态网站,默认所有的 HTML 文件都放在 public 目录。

λ hugo
Building sites … WARN 2019/12/06 16:05:27 found no layout file for "HTML" for "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

| EN
+------------------+----+
Pages | 15
Paginator pages | 0
Non-page files | 0
Static files | 7
Processed images | 0
Aliases | 4
Sitemaps | 1
Cleaned | 0

Total in 126 ms

发布 Hugo 网站

把上面生成的静态网站 public 目录上传至 VPS 网站目录即可,或者可以同步网站到 Github 并使用 Github Pages 托管网站。

使用 Github Pages 托管网站

这部分教程网上非常多,这里简单提一下:首先在 GitHub 上创建一个 Repository,命名为 pronhub.github.io

把 Hugo 配置文件 config.toml 里 basaeURL 修改为 https://pronhub.github.io

然后进入你 public 目录按照正常 Git 命令操作即可:

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

之后更新文章并生成好静态页面后,可以使用 Git push 来同步:

cd public
git add .
git status
git commit -m "add blog post"
git push

关于 Git 的使用说明,可以参考网络上的一大堆教程,这里不再重复。实在不会操作可以跟老杨一样使用 GitHub Desktop 界面版本。

至此,一个简单的(免费) Hugo 静态博客就搭建起来了。

Git 更新文章实例

如果 GitHub 已初始化,本地关联 Git 初始化进行文章更新,可参考以下操作。

创建 SSH Key

在用户主目录(C:\Users\Administrator)下,看看有没有.ssh文件,如果有,再看文件下有没有 id_rsa 和 id_rsa.pub 这两个文件,如果已经有,可直接到下一步。如果没有,打开 Cmder,输入命令,创建 SSH Key

ssh-keygen -t rsa -C "GitHub 邮箱" 

登录 GitHub,打开「Account settings」-「SSH Keys」页面,「Add SSH Key」,填上 Title(随意写),在 Key 文本框里粘贴 id_rsa.pub(默认在 C:\Users\Administrator\.ssh 目录下) 文件里全部内容。

GitHub master 分支根目录与本地 Hugo 生成网站目录 public 对应。

cd pronhub
git clone git@github.com:pronhub/pronhub.git public
hugo
cd public\
git add .
git status
git commit -m "add blog post"
git push

如无意外,博客就更新成功了。

前面 git clone 也可以用 git pull origin master,但是可能会提示「refusing to merge unrelated histories」错误。解决方法:加上 --allow-unrelated-histories 参数

git pull origin master --allow-unrelated-histories

Hugo Bug?

亲测 v0.60.1 和 v0.60.0 两个版本,[https://pronhub.com](https://cyhour.com) 解析出来是 [https://pronhub.com](https://pronhub.com)

旧一点的版本就不会,比如 v0.59.1。

这是 Bug 还是新特性?

Hugo 主题推荐

Vimux:Mainroad,备用下载,点击查看演示

参考资料

使用 Hugo 生成静态博客教程

Hugo 从入门到会用