使用 Hugo 构建静态网站

Hugo 是一个基于 Golang 实现的静态网站框架，以高效构建、灵活扩展等特点而闻名。本文将介绍 Hugo 的各类概念以及使用方法，并使用 Hugo 搭建简单的静态网站。

Hugo 安装#

Hugo 官网：https://gohugo.io/

Hugo 提供了两种版本：标准版本 (standard) 提供了构建网站的基础功能；拓展版本 (extended) 额外还支持 WebP 编码、SASS 等功能。

官方推荐下载拓展版本，macOS 可以通过 Homebrew 进行下载，Windows 可以通过 Chocolatey 或 Scoop 进行下载，也可以选择源码编译的方式安装 Hugo，详情见官方安装文档。

1
2

choco install hugo-extended
hugo version

1
2

scoop install hugo-extended
hugo version

1
2

brew install hugo
hugo version

除此之外，还需要按需安装以下应用。

• Git：代码版本管理工具，用于管理站点内容、主题数据。(推荐, 本文依赖)
• Go：Golang 工具链，用于维护网站 Module 依赖。(可选)
• dart-sass-embedded：SASS 的 Dart 实现版本，部分主题可能依赖。(可选)

站点构建#

创建站点#

安装好 Hugo 和 Git 之后，使用 hugo new site 命令创建站点。

1

hugo new site mywebsite

该命令在当前目录下创建了一个名为 mywebsite 的文件夹，其目录结构和具体用途如下。

├─ archetypes       # 站点文章模板
│   └─ default.md
├─ assets           # 需要被处理的资源 (SCSS、TypeScrpt 等)
├─ content          # 站点文章
├─ data             # 配置文件
├─ layouts          # 站点样式
├─ public           # 最终生成的文件
├─ resources        # 中间缓存 (用于提升站点生成速度)
├─ static           # 静态资源 (图片、CSS、JavaScript 等)
├─ themes           # 主题
├─ .hugo_build.lock # 文件锁 (避免多次运行 Hugo 导致资源处理异常)
└─ config.toml      # 站点配置文件

创建好站点，我们前往站点文件夹下，将该文件夹初始化为一个 Git 仓库。

1
2

cd mywebsite
git init

为了避免将中间产物、最终产物也提交到 Git 仓库中，我们需要添加一个 .gitignore 文件过滤掉这些文件。这里推荐采用 github/gitignore 的方案，可直接点击链接并复制文本。

安装主题#

Hugo 默认不带任何样式，因此在站点成功生成之前，需要为站点安装一个合适的主题。

Hugo 官方罗列了一些主题，可以 点击前往 选择一个适合自己的主题。本文将使用 Hugo 快速入门文档中所使用的主题 Ananke 进行演示。

1

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

1

theme = 'ananke'

1

hugo mod init github.com/<你的Github账号名>/<你的站点仓库名>

1
2

[module]
  proxy = 'https://goproxy.cn,direct'

1

theme = 'github.com/theNewDynamic/gohugo-theme-ananke'

1

hugo mod tidy

1

theme = '<主题名称>'

安装好主题，运行 Hugo 进行站点构建并启动调试服务。

1

hugo server

此时 Hugo 会监听 localhost:1313，我们可通过浏览器访问地址查看站点，到此为止，我们的站点已经顺利完成构建。

站点创作#

创建一篇新文章#

静态站点离不开文章的点缀，Hugo 不会提供默认的示例文章，我们可以通过 hugo new 命令去创建一篇新文章。

1

hugo new posts/hello-world.md

该命令会根据文章模板 archetypes/default.md 创建文件 content/posts/hello-world.md。

1
2
3
4
5
6
7

---
title: "你好，世界"              # 标题
date: 2023-03-11T20:39:21+08:00 # 创建日期
draft: true                     # 是否为草稿
---

你好，这是我的个人站点，希望大家能互相交流、学习，共同进步。

简单修改 Markdown 文件后可以运行 Hugo 查看效果。

1

hugo server -D # -D, --buildDrafts 指定同时渲染草稿文章

创建带资源的文章#

部分文章需要引入图片、视频、音频等静态资源，Hugo 提供一些文章组织结构来支持这类场景。

当一个文件夹下包含了 index.md 文件时，那么这个文件夹将被声明为一个 Page Bundle，即被视为一篇文章，index.md 即为文章的内容，而其他文件被视为这篇文章的资源。

1

hugo new posts/learn-hugo/index.md

通过上述命令创建文章，并导入和使用图片 image.svg。站点最终的目录结构和生成产物的路径如下。

└─ content
    └─ posts
        ├─ learn-hugo
        │   ├─ image.svg  # => /posts/learn-hugo/image.svg
        │   └─ index.md   # => /posts/learn-hugo/index.html
        └─ hello-world.md # => /posts/hello-world/index.html

此时，如果我们在 learn-hugo 文件夹下创建一个新的 Markdown 文件，这个新的文件既不会被渲染也不会被打包，因为它不被视为文章 (页面)。

创建文章系列#

我们可能有一系列类似的文章，希望将它们组织在一个文件夹下，并且有一个整体介绍的文章页面。比如以下的组织结构。

/series/learn-hugo/index.html              # 系列的介绍
/series/learn-hugo/day1-install/index.html # 系列1：安装
/series/learn-hugo/day2-build/index.html   # 系列2：构建
/series/learn-hugo/day3-custom/index.html  # 系列3：自定义

这里是不能通过创建 index.md 来介绍系列的，因为一旦创建，该文件夹下其他文件则被视为资源了。因此 index.md 只能存放在目录结构的叶子节点下。

Hugo 提供了另一种预设的组织结构，通过创建 _index.md 来声明当前文件夹是一个 Branch Bundle，相当于目录结构的非叶子节点。具体目录结构和产物路径如下。

└─ content
    └─ series
        └─ learn-hugo
            ├─ day1-install.md # => /series/learn-hugo/day1-install/index.html
            ├─ day2-build.md   # => /series/learn-hugo/day2-build/index.html
            ├─ day3-custom
            │   ├─ image.svg   # => /series/learn-hugo/day3-custom/image.svg
            │   └─ index.md    # => /series/learn-hugo/day3-custom/index.html
            └─ _index.md       # => /series/learn-hugo/index.html

运行 Hugo 并访问 http://localhost:1313/series/learn-hugo/ 即可阅读系列介绍和系列文章列表。不过你此刻应该发现了，_index.md 并没有在首页的文章列表中，因此我们需要在某一个地方配置入口链接，比如在某篇文章中插入链接、在站点顶部菜单插入链接。

站点修饰#

默认的站点配置文件 config.toml 比较简单，目前仅有以下内容。

1
2
3
4
5
6
7

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = 'github.com/theNewDynamic/gohugo-theme-ananke'

[module]
  proxy = 'https://goproxy.cn,direct'

由于不同主题的配置不尽相同，这里不会展开介绍。 不论什么主题，均可自行参考主题提供的帮助文档对站点配置文件进行修改，修饰站点使得其更加适应、美观、丰富。

比如，Ananke 允许在顶部添加菜单，修改 config.toml 添加菜单配置。

1
2
3
4
5
6
7
8
9

[menu]
[[menu.main]]
  name = '首页'
  url = '/'
  weight = 1
[[menu.main]]
  name = 'Hugo学习'          # 名字
  url = '/series/learn-hugo' # 跳转链接
  weight = 2                 # 权重, 越低位置越前

这样我们就可以把之前创建的“Hugo学习”系列的入口放到站点顶部菜单了。

结语#

本文已简单介绍 Hugo 从安装到使用的基本方法，更强大、丰富的功能可以阅读你所选择的主题的相关文档或 Hugo 官方文档。