Hugo 是使用 Go语言 开发的静态网站生成器(Static Site Generator, SSG)。比起大多数同类工具,Hugo 更加简单和高效。Hugo 的 Slogan 就是:全球最快的网站建设框架(The world’s fastest framework for building websites)。

Hugo 支持制作各种静态网站,支持各种静态网站托管服务,为博客、文档、产品、官网等展示类网站提供了非常有效的低成本解决方案。而且,Hugo 的可扩展性和定制能力赋予了专业人员更多的生产力。

本文使用 Hugo 搭建一个博客笔记写作环境,并为部署到互联网做好准备。

1. 安装Hugo

Windows 请先安装 Scoop,Mac 请先安装 Homebrew

Windows 请启动 PowerShell 或 Windows Terminal,Mac 请打开终端或 iTerm2。

1
2
3
4
5
scoop install hugo  # Windows
brew install hugo   # macOS
snap install hugo   # Linux

hugo version        # 确认安装

2. 创建项目

按照惯例,要为Hugo静态博客项目准备一个文件夹,比如 C:\User\[YOURNAME]\hugo~/Documents/hugo 。世人都晓得 Microsoft ♥ Linux,只是 Windows 盘符依旧。建议:数据不要放 C 盘。

1
2
3
# 新建网站项目
hugo new site /path/to/site
cd /path/to/site

查看项目目录结构如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
$ tree .
.
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

6 directories, 2 files

其中,两个文件分别是网站配置文件和文章模板文件,各个文件夹的作用如下:

  • archetypes:包含内容模板文件。
  • content:包含网站内容文件,通常使用 markdown 格式。
  • data: 可以为网站内容文件提供数据。
  • layouts:包含网站模版文件。优先级高于 /themes/<THEME>/layouts/
  • static:包含 CSS、JavaScript、图片等静态资源文件。
  • themes: 存放网站主题。

content 文件夹支持按层级组织内容,支持URL定制以方便对内容的访问,详见官方文档

3. 安装主题

主题是什么,简单说,就是衣装。人靠衣装马靠鞍。

Hugo 官网有很多主题可选,本文使用的 Even 是一款轻简博客主题。

1
2
3
4
5
# 安装 Even 主题
git init
git submodule add https://github.com/olOwOlo/hugo-theme-even themes/even
cp themes/even/exampleSite/config.toml ./
echo 'public/' >> .gitignore

可以使用 Favicon 在线生成器 制作自己的 favicon。将生成的文件复制到 static 目录下即可。具体复制哪些文件请参考 themes/even/static 文件夹中的内容。

4. 添加文章

1
2
3
4
# 添加第一篇文章
hugo new post/my-first-post.md
# 注意:even 主题使用 post 而不是 posts
# 格式:hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>

以上命令将在 content 文件夹中创建相应的目录和文件,然后使用文本编辑器或Markdown编辑器打开文件,使用 Markdown 语法 编辑文章的内容。

1
2
# 编辑文章 (命令使用 VSCode)
code content/post/my-first-post.md
1
2
3
4
5
6
7
---
title: "My First Post"
date: 2020-03-20T21:08:09+08:00
draft: true
---

Hello World!

文中头部 --- 括起的部分,称为 Front Matter,内容来自 archetypes/default.md(文章内容模板),定义了当前博客文章的 Metadata,参与网页生成与控制。其中---表示使用了 YAML 格式,详见官方文档。可将文章模板替换为主题提供的模板文件,即 cp themes/even/archetypes/default.md ./archetypes/

Front Matter 中的一些配置如下:

1
2
3
4
5
6
7
8
---
tags: [""]  # 文章技术、内容、知识点 - 是什么
categories: [""]  # 文章所属专题类别 - 能做什么
draft: true  # 草稿需使用 -D 参数
author: ""  # 可单独设置文章作者
weight: 10  # 文章列表排序权重
toc: true  # 是否开启文章目录
---

5. 本地服务

1
2
3
# 启动服务
hugo server -D
# -D 选项表示包含草稿,即 draft=true 的文章

此命令将启动一个 Web 服务,输出内容如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
Building sites …
                   | EN
-------------------+-----
  Pages            | 10
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  5
  Processed images |  0
  Aliases          |  2
  Sitemaps         |  1
  Cleaned          |  0

Built in 8 ms
Watching for changes in D:\hugo\blog\{archetypes,content,data,layouts,static,themes}
Watching for config changes in D:\hugo\blog\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/。现在,你有了一个本地运行的博客网站。尝试在编辑器里修改文章的内容,保存。几乎同时,网站的内容更新了,这就是 Live Reload

端口号1313可能会发生改变,可使用 -p 参数指定端口号,如 hugo server -p 8080

6. 配置主题

装起来,正是我们生命的主题。

1
2
# 编辑配置文件
code config.toml

配置文件 config.toml 包含了很多参数,可以对网站和主题进行定制:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
baseURL = "https://markzhan.com/blog"
defaultContentLanguage = "zh-cn"
title = "马克博格"

[author]
  name = "mark"

[Permalinks]
  post = "/:year/:month/:day/:filename/"

...

配置文件中,大部分配置项都有注释。对于开发者来说,为使用者提供文档十分重要;对于使用者来说,好的文档只是一个好的开始。尝试修改,观察变化,勇于探索,才是学习之道。更多配置请查看文档

在本地运行Hugo服务,baseURL 的域名部分是无效的,但路径部分是有效的。如果修改了 baseURL 且其中包含路径,如 /blog,那么本地访问网址应修改为 http://localhost:1313/blog

7. 预发布

如何让别人能够访问到我们的网站,内网穿透还是部署到互联网,通常还是部署到互联网。不过,在不远的将来,基于区块链和家庭数据中心的部署方式必将大行其道。

1
2
3
# 准备发布
hugo  # 生成静态网站,或:
hugo -D  # 包含 draft = true 的文章

生成的网站文件保存在 public 目录中。由于Hugo生成的是静态网站,不需要为静态网站配置任何代码执行环境,只要将 public 目录上传到互联网 Web 服务器的相应目录中,即可实现线上部署。

如果你安装了 Node.js,可使用 serve 在本地体验静态网站:

1
2
3
4
cd public
npm i -g serve
serve .
open http://localhost:5000

结束语

现在,你已经拥有了一个本地的写作环境,可以用你最喜欢的编辑器写博客、记笔记,实现这些只需要执行几条命令。接下来,只需要简单配置即可一键部署 Hugo 博客到 VPS

如果你想了解更多,NetlifyStaticGen 非常不错。这是一个开源静态网站生成器列表和静态网站一键托管服务,涵盖各种技术实现,让你快速对号入座。