本文介绍如何使用 hugo 搭建站点。

概述

hugo 号称“世界上最快的静态网站生成器”。

hugo cli

自动补全

为 zsh 安装自动补全：

hugo completion zsh > $(brew --prefix)/share/zsh/site-functions/_hugo
shell

参见 zsh 自动补全

其他 shell 安装参见 hugo completion

生成站点

通过命令hugo new site my-site生成默认的文件，目录结构如下：

my-site
├── archetypes
│   └── default.md
├── assets
├── content
├── data
├── hugo.toml
├── i18n
├── layouts
├── static
└── themes
bash

启动站点

hugo server -D
bash

配置

hugo 支持多种文件格式（toml/yaml/json）的 配置，默认配置是位于根目录下的 hugo.yaml 文件。

除了使用单一的站点配置文件，还可以将配置按环境、根配置键和语言拆分放在config目录下：

my-project/
└── config/
    ├── _default/
    │   ├── hugo.yaml
    │   ├── menus.en.yaml
    │   ├── menus.de.yaml
    │   └── params.yaml
    └── production/
        └── params.toml
bash

FAQ

查看当前站点的配置

hugo config --format yaml
shell

更多命令行使用参见 cli

数学公式

如果在文章中用到数学公式，通常有两个方案：

modules

Hugo modules 是 Hugo 的核心构建组件。module 可以是主项目，也可以是一个小组件，用来提供 Hugo 中定义的 7 种组件类型（static, content, layouts, data, assets, i18n, and archetypes）中的一种或多种。

可以任意组合 module，甚至可以挂载非 Hugo 项目的目录，形成一个虚拟的大联合文件系统。

Hugo module 由 Go module 提供支持。有关 Go module 的更多信息，请参阅：

我们可以 通过 module 来使用 theme，比如当前博客主题就是通过 module 挂载的：

[module]
  [[module.imports]]
    path = 'github.com/razonyang/hugo-theme-bootstrap'
toml
module:
  imports:
  - path: github.com/razonyang/hugo-theme-bootstrap
yaml
{
   "module": {
      "imports": [
         {
            "path": "github.com/razonyang/hugo-theme-bootstrap"
         }
      ]
   }
}
json

Hugo Modules: everything you need to know!

查看 mounts 的 config：

hugo config mounts
shell

主题

模板

// npm install -g prettier prettier-plugin-go-template
{
"plugins": ["prettier-plugin-go-template"],
"overrides": [
{
"files": ["*.html"],
"options": {
"parser": "go-template"
}
}
]
}
view raw .prettierrc hosted with ❤ by GitHub

流行主题

部署

Build check

Push 到仓库前可以先进行本地 build 来检查是否有错误，避免 Github Action 出错到站站点更新失败，这个功能可以通过 husky 配置为 git hook 来自动化。

npx husky add ./husky/pre-push "hugo && rm -fr public"

GitHub Pages

官方 Host on GitHub pages 介绍如何通过 GitHub Action 而不是以前 branch 的方式来部署。

延伸阅读