这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

开始入门

Get Started - 开始入门

https://gohugo.io/getting-started/

​ 如果这是您第一次使用 Hugo,而且已经在计算机上安装了 Hugo,则建议使用快速入门。您也可以使用外部学习资源学习 Hugo。

1 - 快速入门

Quick Start - 快速入门

https://gohugo.io/getting-started/quick-start/

​ 学习如何在几分钟内创建一个 Hugo 站点。

​ 在本教程中,您将会:

  1. 创建一个站点
  2. 添加内容
  3. 配置站点
  4. 发布站点

先决条件

​ 在开始本教程之前,您必须:

  1. 安装 Hugo(扩展版)
  2. 安装 Git

​ 您还必须熟悉使用命令行操作。

创建一个站点

命令

如果您是 Windows 用户:

  • 不要使用命令提示符
  • 不要使用 Windows PowerShell
  • 请在 PowerShell 或类似于 WSL 或 Git Bash 的 Linux 终端中运行这些命令。

PowerShell 和 Windows PowerShell 是不同的应用程序。

​ 运行以下命令创建带有 Ananke主题的 Hugo 站点。下一节将对每个命令进行解释。

1
2
3
4
5
6
hugo new site quickstart
cd quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> config.toml
hugo server

​ 在终端中显示的 URL 上查看您的站点。按 Ctrl + C 停止 Hugo 的开发服务器。

命令解释

​ 在 quickstart 目录中为项目创建目录结构

1
hugo new site quickstart

​ 将当前目录切换为项目根目录:

1
cd quickstart

​ 在当前目录中初始化一个空的 Git 存储库:

1
git init

​ 将 Ananke主题克隆到 themes 目录中,并将其作为 Git submodule添加到项目中。

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

​ 在站点配置文件中添加一行,指示当前主题:

1
echo "theme = 'ananke'" >> config.toml

​ 启动 Hugo 的开发服务器以查看站点:

1
hugo server

​ 按 Ctrl + C 停止 Hugo 的开发服务器。

添加内容

​ 在站点中添加一个新页面:

1
hugo new posts/my-first-post.md

​ Hugo 在 content/posts 目录中创建了该文件。使用您的编辑器打开该文件。

1
2
3
4
5
---
title: "My First Post"
date: 2022-11-20T09:03:20-08:00
draft: true
---

​ 请注意,前置元数据中的draft值为 true。默认情况下,Hugo 不会在构建站点时发布草稿(draft)内容。了解有关草稿(draft)、将来(future)和过期(expired)内容的更多信息。

​ 在文章的正文中添加一些 markdown,但不要更改draft的值。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
title: "My First Post"
date: 2022-11-20T09:03:20-08:00
draft: true
---
## Introduction

This is **bold** text, and this is *emphasized* text.

Visit the [Hugo](https://gohugo.io) website!

​ 保存文件,然后启动 Hugo 的开发服务器以查看站点。您可以运行以下任一命令来包含草稿内容。

1
2
hugo server --buildDrafts
hugo server -D

​ 在终端中显示的 URL 上查看您的站点。随着您继续添加和更改内容,请保持开发服务器运行。

​ Hugo 的渲染引擎符合 CommonMark 的 markdown 规范。CommonMark组织提供了一个有用(由参考实现驱动)的实时测试工具

配置站点

​ 使用编辑器打开项目根目录中的站点配置文件(config.toml)。

1
2
3
4
baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = 'ananke'

​ 进行以下更改:

  1. baseURL设置为您的生产站点。此值必须以协议开头,并以斜杠结尾,如上所示。
  2. languageCode设置为您的语言和地区。
  3. 设置生产站点的title

​ 启动Hugo的开发服务器以查看更改,记得包括草稿内容。

1
hugo server -D

​ 大多数主题作者都会提供配置指南和选项。请务必访问您的主题存储库或文档站点了解详情。

​ Ananke主题的作者The New Dynamic为配置和使用提供文档。他们还提供演示站点

发布站点

​ 在此步骤中,您将发布站点,但不会部署它。

​ 发布站点时,Hugo会在项目根目录中的public目录中创建整个静态站点。这包括HTML文件和assets,如图片、CSS文件和JavaScript文件。

​ 在发布站点时,通常不希望包括草稿(draft)、将来(future)和过期(expired)内容。命令很简单。

1
hugo

​ 要了解如何部署站点,请参阅主机和部署部分。

寻求帮助

​ Hugo的论坛是一个活跃的用户和开发者社区,他们回答问题、分享知识和提供示例。超过20,000个主题的快速搜索通常可以回答您的问题。请确保在提问之前阅读有关请求帮助的信息。

其他资源

​ 有关帮助您学习Hugo的其他资源,包括书籍和视频教程,请参见外部学习资源页面。

另请参阅

2 - 基础用法

Basic usage - 基础用法

https://gohugo.io/getting-started/usage/

​ Hugo的命令行界面(CLI)功能齐全但简单易用,即使对于那些在命令行上有限经验的人也是如此。

测试您的安装

安装完Hugo后,请通过运行以下命令来测试您的安装:

1
hugo version

​ 您应该会看到类似于以下的输出:

1
hugo v0.105.0-0e3b42b4a9bdeb4d866210819fc6ddcf51582ffa+extended linux/amd64 BuildDate=2022-10-28T12:29:05Z VendorInfo=snap:0.105.0

显示可用命令

​ 要查看可用命令和标志的列表:

1
hugo help

​ 要获取子命令的帮助,请使用--help标志。例如:

1
hugo server --help

构建您的站点

​ 要构建您的站点,请cd进入您的项目目录并运行:

1
hugo

hugo命令将构建您的站点,将文件发布到public目录中。要将您的站点发布到不同的目录中,请使用--destination标志在您的站点配置中设置publishDir

​ Hugo在构建您的站点之前不会清除public目录。现有的文件将被覆盖,但不会被删除。这种行为是有意的,以防止意外删除您在构建之后添加到public目录中的文件。

​ 根据您的需求,您可能希望在每次构建之前手动清除public目录的内容。

草稿、未来和过期内容

​ Hugo允许您在内容的前置元数据中设置draftdatepublishDateexpiryDate。默认情况下,Hugo不会发布以下内容:

  • draft值为true
  • date在未来时
  • publishDate在未来时
  • expiryDate在过去时

​ 您可以在运行hugohugo server时使用命令行标志来覆盖默认行为:

1
2
3
hugo --buildDrafts    # or -D
hugo --buildExpired   # or -E
hugo --buildFuture    # or -F

​ 尽管您也可以在站点配置中设置这些值,但除非所有内容作者都知道并理解这些设置,否则可能会导致意想不到的结果。

​ 正如上面所述,Hugo 在构建站点之前不会清除 public 目录。根据上述四个条件的当前评估,构建后您的 public 目录可能包含来自上一次构建的不必要的文件。

​ 一种常见的做法是在每次构建之前手动清除 public 目录的内容,以删除草稿、过期和未来的内容。

开发和测试您的站点

​ 为了在开发布局或创建内容时查看您的站点,请cd进入项目目录并运行:

1
hugo server

hugo server 命令将您的站点构建到内存中,并使用最小的 HTTP 服务器提供您的页面。运行 hugo server 时,它将显示您本地站点的 URL:

1
Web Server is available at http://localhost:1313/ 

​ 在服务器运行时,它会监视项目目录中的资源、配置、内容、数据、布局、翻译和静态文件的更改。当它检测到更改时,服务器会重新构建您的站点并使用 LiveReload刷新您的浏览器。

​ 大多数 Hugo 构建速度都非常快,除非您直接查看浏览器,否则可能不会注意到更改。

LiveReload

​ 在服务器运行时,Hugo 会将 JavaScript 注入生成的 HTML 页面中。LiveReload 脚本通过 Web sockets 创建了一个从浏览器到服务器的连接。您不需要安装任何软件或浏览器插件,也不需要任何配置。

自动重定向

​ 当编辑内容时,如果您希望浏览器自动重定向到您最后修改的页面,请运行:

1
hugo server --navigateToChanged

部署您的站点

​ 如上所述,Hugo 在构建站点之前不会清空 public 目录。在每次构建之前手动清空 public 目录以删除草稿、已过期和未来的内容。

​ 当您准备部署您的站点时,运行:

1
hugo

​ 这会构建您的站点,并将文件发布到 public 目录。目录结构将类似于:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
public/
├── categories/
│   ├── index.html
│   └── index.xml  <-- RSS feed for this section
├── post/
│   ├── my-first-post/
│   │   └── index.html
│   ├── index.html
│   └── index.xml  <-- RSS feed for this section
├── tags/
│   ├── index.html
│   └── index.xml  <-- RSS feed for this section
├── index.html
├── index.xml      <-- RSS feed for the site
└── sitemap.xml

​ 在一个简单的托管环境中,您通常会通过 ftprsyncscp 将您的文件传输到虚拟主机的根目录,public 目录的内容就是您所需的全部内容。

​ 我们的大多数用户使用 CI/CD 工作流部署其站点,其中对 GitHub 或 GitLab 存储库的推送触发了构建和部署。流行的提供者包括 AWS AmplifyCloudCannonCloudflare PagesGitHub PagesGitLab PagesNetlify

​ 在托管和部署部分中了解更多信息。


  1. Git 存储库包含整个项目目录,通常不包括 public 目录,因为在push之后才构建站点。↩︎

另请参阅

3 - 目录结构

Directory Structure - 目录结构

https://gohugo.io/getting-started/directory-structure/

​ Hugo的CLI脚手架会创建一个项目目录结构,然后使用该单个目录作为输入来创建一个完整的站点。

新建站点脚手架

​ 从命令行运行hugo new site example会创建一个带有以下元素的目录结构:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
example/
├── archetypes/
│   └── default.md
├── assets/
├── content/
├── data/
├── layouts/
├── public/
├── static/
├── themes/
└── config.toml

目录结构说明

​ 以下是每个目录的高级概述,并提供了链接到Hugo文档中各自部分的链接。

  • archetypes

    您可以使用hugo new命令在Hugo中创建新的内容文件。默认情况下,Hugo将创建带有datetitle(从文件名推断)和draft = true的新内容文件。这节省了时间,并为使用多个内容类型的站点促进了一致性。您还可以创建自己的原型(archetypes),其中包含自定义的预配置前置元数据字段。

  • assets

    存储需要由Hugo Pipes处理的所有文件。只有使用.Permalink.RelPermalink的文件将被发布到public目录。

  • config

    Hugo带有大量的配置指令config目录是存储这些指令的地方,以JSON、YAML或TOML文件的形式存储。每个根设置对象都可以作为自己的文件,并按环境结构化。设置最少且不需要环境感知的项目可以在其根目录使用单个config.toml文件。

    许多站点可能不需要任何配置,但Hugo提供了大量的配置指令,用于更精细的指导如何构建您的站点。注意:config目录不会默认创建。

  • content

    您站点的所有内容都将位于此目录中。Hugo中的每个顶层文件夹都被视为内容章节。例如,如果您的站点有三个主要章节——博客(blog)、文章(articles)和教程(tutorials)——则在content/blogcontent/articlescontent/tutorials中将会有三个目录。Hugo使用章节来分配默认内容类型

  • data

    此目录用于存储在生成站点时Hugo可以使用的配置文件。您可以按YAML、JSON或TOML格式编写这些文件。除了将这些文件添加到此文件夹中外,您还可以创建从动态内容中提取的数据模板

  • layouts

    存储模板,以.html文件的形式指定如何将您的内容视图渲染为静态站点。模板包括列表页面主页分类法模板局部单页模板等。

  • static

    存储所有的静态内容:图片、CSS、JavaScript等。当Hugo构建您的站点时,static目录内的所有资源都将按原样复制。一个使用static目录的好例子是在Google Search Console上验证站点所有权,您希望Hugo复制完整的HTML文件而不修改其内容。

​ 从 Hugo 0.31 版本开始,您可以有多个静态目录。

  • resources

    缓存一些文件以加速生成。也可以由模板作者用于分发已构建的 Sass 文件,这样您就不必安装预处理器。注意:默认情况下不会创建resources 目录。

另请参阅

4 - 配置 Hugo

Configure Hugo - 配置 Hugo

https://gohugo.io/getting-started/configuration/

​ 如何配置您的 Hugo 站点。

配置文件

​ Hugo 使用 config.tomlconfig.yamlconfig.json(如果在站点根目录中找到)作为默认的站点配置文件。

​ 用户可以使用命令行 --config 开关选择覆盖默认设置的一个或多个站点配置文件。

例如:

1
2
hugo --config debugconfig.toml
hugo --config a.toml,b.toml,c.toml

​ 可以将多个站点配置文件指定为逗号分隔的字符串传递给 --config 开关。

hugo.toml vs config.toml

​ 在 Hugo 0.110.0 中,我们将默认的配置基础文件名更改为 hugo,例如 hugo.toml。我们仍会查找 config.toml 等文件,但我们建议您最终将其重命名(但如果您想支持旧版本的 Hugo,则需要等待)。我们这样做的主要原因是为了让代码编辑器和构建工具更容易识别这是 Hugo 的配置文件和项目。

v0.110.0 新功能

配置目录

​ 除了使用单个站点配置文件外,您还可以使用 configDir 目录(默认为 config/)来维护更易于组织和特定于环境的设置。

  • 每个文件都代表一个配置根对象,例如 params.toml 代表 [Params]menu(s).toml 代表 [Menu]languages.toml 代表 [Languages] 等等…
  • 每个文件的内容必须是顶级的,例如:

config.

=== “yaml”

```yaml
Params:
  foo: bar
```

=== “toml”

```toml
[Params]
  foo = 'bar'
```

=== “json”

```json
{
    "Params": {
          "foo": "bar"
    }
}
```

params.

=== “yaml”

```yaml
foo: bar
```

=== “toml”

```toml
foo = 'bar'
```

=== “json”

```json
{
   "foo": "bar"
}
```
  • 每个目录保存了一组文件,包含特定环境的设置。
  • 文件可以本地化,变成特定语言。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
├── config
│   ├── _default
│   │   ├── config.toml
│   │   ├── languages.toml
│   │   ├── menus.en.toml
│   │   ├── menus.zh.toml
│   │   └── params.toml
│   ├── production
│   │   ├── config.toml
│   │   └── params.toml
│   └── staging
│       ├── config.toml
│       └── params.toml

​ 考虑上述结构,在运行hugo --environment staging命令时,Hugo将使用config/_default中的所有设置,并在其上合并staging的设置。

​ 让我们举个例子来更好地理解这个过程。假设您的站点使用Google Analytics。这要求您在config.toml中指定googleAnalytics = "G-XXXXXXXX"。现在考虑以下场景:

  • 您不希望在开发中加载分析代码,即在localhost上。
  • 您想为生产和staging环境使用不同的googleAnalytics ID:
    • 生产环境的G-PPPPPPPP
    • staging环境的G-SSSSSSSS

​ 考虑上述情况,您需要如何配置您的config.toml文件:

  1. _default/config.toml中,您根本不需要提及googleAnalytics参数。这可以确保在您运行hugo server时,即在您的开发服务器上不加载Google Analytics代码。这是因为,当您运行hugo server时,默认情况下Hugo设置Environment=development,它使用_default文件夹中的配置文件。

  2. production/config.toml中,您只需要有一行:

    googleAnalytics = "G-PPPPPPPP"

    您不需要在此配置文件中再次提及所有其他参数,如titlebaseURLtheme等。您只需要提及那些不同或新的生产环境参数。这是由于Hugo将在_default/config.toml之上合并此参数。现在,当您运行hugo(build命令)时,默认情况下hugo设置Environment=production,因此G-PPPPPPPP分析代码将存在于您的生产站点中。

  3. 同样,在staging/config.toml中,您只需要有一行:

    googleAnalytics = "G-SSSSSSSS"

    现在,您需要告诉Hugo您正在使用staging环境。因此,您的构建命令应该是hugo --environment staging,这将在您的staging站点中加载G-SSSSSSSS分析代码。

​ 默认环境是hugo server下的development和hugo下的production

合并主题配置

_merge 的配置值可以是以下之一:

  • none

    不合并。

  • shallow

    仅添加新键的值。

  • deep

    添加新键的值,合并现有键的值。

​ 请注意,您不需要像下面的默认设置那样冗长;如果未设置,则会继承更高的_merge值。

config.

=== “yaml”

```yaml
build:
  _merge: none
caches:
  _merge: none
cascade:
  _merge: none
frontmatter:
  _merge: none
imaging:
  _merge: none
languages:
  _merge: none
  en:
    _merge: none
    menus:
      _merge: shallow
    params:
      _merge: deep
markup:
  _merge: none
mediatypes:
  _merge: shallow
menus:
  _merge: shallow
minify:
  _merge: none
module:
  _merge: none
outputformats:
  _merge: shallow
params:
  _merge: deep
permalinks:
  _merge: none
privacy:
  _merge: none
related:
  _merge: none
security:
  _merge: none
sitemap:
  _merge: none
taxonomies:
  _merge: none
```

=== “toml”

```toml
[build]
  _merge = 'none'
[caches]
  _merge = 'none'
[cascade]
  _merge = 'none'
[frontmatter]
  _merge = 'none'
[imaging]
  _merge = 'none'
[languages]
  _merge = 'none'
  [languages.en]
    _merge = 'none'
    [languages.en.menus]
      _merge = 'shallow'
    [languages.en.params]
      _merge = 'deep'
[markup]
  _merge = 'none'
[mediatypes]
  _merge = 'shallow'
[menus]
  _merge = 'shallow'
[minify]
  _merge = 'none'
[module]
  _merge = 'none'
[outputformats]
  _merge = 'shallow'
[params]
  _merge = 'deep'
[permalinks]
  _merge = 'none'
[privacy]
  _merge = 'none'
[related]
  _merge = 'none'
[security]
  _merge = 'none'
[sitemap]
  _merge = 'none'
[taxonomies]
  _merge = 'none'
```

=== “json”

```json
{
   "build": {
      "_merge": "none"
   },
   "caches": {
      "_merge": "none"
   },
   "cascade": {
      "_merge": "none"
   },
   "frontmatter": {
      "_merge": "none"
   },
   "imaging": {
      "_merge": "none"
   },
   "languages": {
      "_merge": "none",
      "en": {
         "_merge": "none",
         "menus": {
            "_merge": "shallow"
         },
         "params": {
            "_merge": "deep"
         }
      }
   },
   "markup": {
      "_merge": "none"
   },
   "mediatypes": {
      "_merge": "shallow"
   },
   "menus": {
      "_merge": "shallow"
   },
   "minify": {
      "_merge": "none"
   },
   "module": {
      "_merge": "none"
   },
   "outputformats": {
      "_merge": "shallow"
   },
   "params": {
      "_merge": "deep"
   },
   "permalinks": {
      "_merge": "none"
   },
   "privacy": {
      "_merge": "none"
   },
   "related": {
      "_merge": "none"
   },
   "security": {
      "_merge": "none"
   },
   "sitemap": {
      "_merge": "none"
   },
   "taxonomies": {
      "_merge": "none"
   }
}
```

所有配置设置

​ 以下是Hugo定义的变量的完整列表。用户可以选择在其站点配置文件中覆盖这些值。

archetypeDir

​ 默认值:“archetypes”

​ Hugo查找原型文件(内容模板)的目录。另请参阅模块挂载配置,以了解配置此目录的另一种替代方式(从Hugo 0.56开始)。

assetDir

​ 默认值:“assets”

​ Hugo查找Hugo Pipes中使用的资产文件的目录。另请参阅模块挂载配置,以了解配置此目录的另一种替代方式(从Hugo 0.56开始)。

baseURL

​ 您发布站点的绝对 URL(协议、主机、路径和尾随斜杠),例如 https://www.example.org/docs/

build

​ 请参阅配置构建

buildDrafts (false)

​ 默认值:false

​ 在构建时包括草稿。

buildExpired

​ 默认值:false

​ 包括已过期的内容。

buildFuture

​ 默认值:false

​ 包括发布日期在未来的内容。

caches

​ 请参阅配置文件缓存

cascade

​ 将默认配置值(正面)传递到内容树中的页面。站点配置中的选项与页面前置元数据相同,请参阅前置元数据层叠

canonifyURLs

​ 默认值:false

​ 启用将相对URL转换为绝对URL。

cleanDestinationDir

​ 默认值:false

​ 在构建时,从目标中删除在static 目录中找不到的文件。

contentDir

​ 默认值:“content”

​ Hugo读取内容文件的目录。也可以参考模块安装配置的另一种方式来配置此目录(从Hugo 0.56开始)。

​ 默认值:""

​ 站点的版权声明,通常显示在页脚上。

dataDir

​ 默认值:“data”

​ Hugo读取数据文件的目录。也可以参考模块安装配置的另一种方式来配置此目录(从Hugo 0.56开始)。

defaultContentLanguage <-

​ 默认值:“en”

​ 没有语言标识的内容将默认为此语言。

defaultContentLanguageInSubdir

​ 默认值:false

​ 在子目录中呈现默认的内容语言,例如content/en/。站点根目录/将重定向到/en/

disableAliases

​ 默认值:false

​ 禁用别名重定向的生成。请注意,即使设置了disableAliases,别名本身仍将保留在页面上。这样做的动机是能够在.htaccess、Netlify _redirects文件或类似的输出格式中使用301重定向。

disableHugoGeneratorInject

​ 默认值:false

​ Hugo默认情况下仅在主页的HTML头中插入一个生成器元标记。您可以关闭它,但我们真的很希望您不要这样做,因为这是观察Hugo的受欢迎程度的好方法。

disableKinds

​ 默认值:[]

​ 启用禁用指定类型的所有页面。在此列表中允许的值为:"page""home""section""taxonomy""term""RSS""sitemap""robotsTXT""404"

disableLiveReload

​ 默认值:false

​ 禁用浏览器窗口的自动实时重新加载。

disablePathToLower

​ 默认值:false

​ 不要将url/path转换为小写。

enableEmoji <-

​ 默认值:false

​ 为页面内容启用表情符号支持;参见Emoji备忘表

enableGitInfo <-

​ 默认值:false

​ 为每个页面启用.GitInfo对象(如果Hugo站点已经通过Git进行版本控制)。这将使用每个内容文件的最后git提交日期来更新每个页面的Lastmod参数。

enableInlineShortcodes

​ 默认值:false

​ 启用内联shortcode 支持。参见内联shortcode

enableMissingTranslationPlaceholders

​ 默认值:false

​ 如果缺少翻译,则显示占位符,而不是默认值或空字符串。

enableRobotsTXT <-

​ 默认值:false

​ 启用robots.txt文件的生成。

frontmatter

​ 请参阅前置元数据配置

googleAnalytics

​ 默认值:""

​ Google Analytics 跟踪 ID。

hasCJKLanguage <-

​ 默认值:false

​ 如果为 true,则自动检测内容中的中文/日文/韩文语言。这将使得 .Summary.WordCount 在 CJK 语言中正确工作。

imaging

​ 请参阅图像处理配置

languageCode

​ 默认值:""

​ 由 RFC 5646 定义的语言标签。此值用于填充:

languages

​ 请参阅配置语言

disableLanguages

​ 请参阅禁用语言

markup

​ 请参阅配置标记

mediaTypes

​ 请参阅配置媒体类型

​ 请参阅菜单

minify

​ 请参阅配置 Minify

module

​ 模块配置,请参阅模块配置

newContentEditor

​ 默认值:""

​ 创建新内容时要使用的编辑器。

noChmod

​ 默认值:false

​ 不同步文件的权限模式。

noTimes

​ 默认值:false

​ 不同步文件的修改时间。

outputFormats

​ 请参阅配置输出格式

paginate <-

​ 默认值:10

分页中每页的默认元素数。

paginatePath

​ 默认值:“page”

​ 在分页期间使用的路径元素(https://example.com/page/2)。

​ 请参阅内容管理

pluralizeListTitles

​ 默认值:true

​ 在列表中使用复数形式的标题。

publishDir

​ 默认值:“public”

​ Hugo将生成的最终静态站点(HTML文件等)写入的目录。

​ 请参阅相关内容(Related Content)。

relativeURLs

​ 默认值:false

​ 启用此选项可使所有相对URL相对于内容根目录。请注意,这不会影响绝对URL。

refLinksErrorLevel

​ 默认值:“ERROR”

​ 使用refrelref解析页面链接时,如果无法解析链接,将以此日志级别记录。有效值为ERROR(默认值)或WARNING。任何ERROR将导致构建失败(exit -1)。

refLinksNotFoundURL

​ 在refrelref中找不到页面引用时要使用的URL占位符。按原样使用。

removePathAccents

​ 默认值:false

​ 从内容路径中的组合字符中删除非间隔标记

1
content/post/hügó.md --> https://example.org/post/hugo/

rssLimit

​ 默认值:-1(无限制)

​ RSS feed中的最大项目数。

sectionPagesMenu

​ 请参阅菜单(Menus)。

security

​ 请参阅安全策略(Security Policy)。

sitemap

​ 默认站点地图配置

summaryLength

​ 默认值:70

​ 在.Summary中显示的文本长度(以单词计算)。

taxonomies

​ 请参阅分类(Configure Taxonomies)。

theme

​ 请参阅模块配置(Module Config)以了解如何导入主题。

themesDir

​ 默认值:“themes”

​ Hugo从中读取主题的目录。

timeout

​ 默认值:“30s”

​ 生成页面内容的超时时间,以持续时间或毫秒表示。注意:这用于退出递归内容生成。如果页面生成较慢(例如因为它们需要大量的图像处理或依赖于远程内容),则可能需要提高此限制。

timeZone <-

​ 用于解析前置元数据日期(不带此信息)和time function的时区(或位置),例如Europe/Oslo。有效值列表可能因系统而异,但应包括UTCLocalIANA时区数据库中的任何位置。

title

​ 站点标题。

titleCaseStyle

​ 默认值:“AP”

​ 请参阅配置标题大小写(Configure Title Case)。

uglyURLs

​ 默认值:false

​ 启用时,将创建形式为/filename.html而不是/filename/的URL。

watch

​ 默认值:false

​ 监视文件系统以进行更改,并根据需要重新创建。

​ 如果您在*nix机器上开发您的站点,这是一个方便的从命令行查找配置选项的快捷方式:

1
2
cd ~/sites/yourhugosite
hugo config | grep emoji

显示输出如下:

1
enableemoji: true

配置构建 -> [build]

build配置部分包含全局构建相关的配置选项。

config.

=== “yaml”

```yaml
build:
  noJSConfigInAssets: false
  useResourceCacheWhen: fallback
  writeStats: false
```

=== “toml”

```toml
[build]
  noJSConfigInAssets = false
  useResourceCacheWhen = 'fallback'
  writeStats = false
```

=== “json”

```json
{
   "build": {
      "noJSConfigInAssets": false,
      "useResourceCacheWhen": "fallback",
      "writeStats": false
   }
}
```
  • useResourceCacheWhen

    决定在 PostCSS 和 ToCSS 中何时使用 /resources/_gen 中的缓存资源。有效值为 neveralwaysfallback。最后一个值表示如果 PostCSS/extended版本不可用,则尝试使用缓存。

  • writeStats

    启用后,将在项目根目录下写入一个名为 hugo_stats.json 的文件,其中包含有关构建的一些汇总数据,例如已发布的 HTML 实体列表,可用于进行 CSS pruning。如果您仅在生产构建中使用此功能,则应考虑将其放在 config/production 下面。值得一提的是,由于部分服务器构建的本质,当您添加或更改 HTML 实体时,将添加新的 HTML 实体,但旧值不会在您重启服务器或运行常规的 hugo 构建之前被删除。

请注意,这是清除未使用的 CSS 的主要用例;它专为速度而建,可能会出现误报(例如,检测到不是 HTML 元素的 HTML 元素)。

  • noJSConfigInAssets

    关闭在 /assets 文件夹中写入一个 jsconfig.json,其中包含来自运行 js.Build 的导入映射。此文件旨在帮助在诸如 VS Code 等代码编辑器内进行智能感知/导航。请注意,如果您不使用 js.Build,则不会写入任何文件。

Configure Server -> [server]

​ 仅在运行 hugo server 时相关,在开发过程中可以设置 HTTP 标头,从而可以测试您的内容安全策略等。配置格式与 Netlify 的格式相匹配,并具有略微更强大的全局匹配功能

config.

=== “yaml”

```yaml
server:
  headers:
  - for: /**
    values:
      Content-Security-Policy: script-src localhost:1313
      Referrer-Policy: strict-origin-when-cross-origin
      X-Content-Type-Options: nosniff
      X-Frame-Options: DENY
      X-XSS-Protection: 1; mode=block
```

=== “toml”

```toml
[server]
[[server.headers]]
  for = '/**'
  [server.headers.values]
    Content-Security-Policy = 'script-src localhost:1313'
    Referrer-Policy = 'strict-origin-when-cross-origin'
    X-Content-Type-Options = 'nosniff'
    X-Frame-Options = 'DENY'
    X-XSS-Protection = '1; mode=block'
```

=== “json”

```json
{
   "server": {
      "headers": [
         {
            "for": "/**",
            "values": {
               "Content-Security-Policy": "script-src localhost:1313",
               "Referrer-Policy": "strict-origin-when-cross-origin",
               "X-Content-Type-Options": "nosniff",
               "X-Frame-Options": "DENY",
               "X-XSS-Protection": "1; mode=block"
            }
         }
      ]
   }
}
```

​ 由于这仅适用于"development only",因此将其放置在development环境下可能是有意义的:

config/development/server.

=== “yaml”

```yaml
headers:
- for: /**
  values:
    Content-Security-Policy: script-src localhost:1313
    Referrer-Policy: strict-origin-when-cross-origin
    X-Content-Type-Options: nosniff
    X-Frame-Options: DENY
    X-XSS-Protection: 1; mode=block
```

=== “toml”

```toml
[[headers]]
for = '/**'
[headers.values]
  Content-Security-Policy = 'script-src localhost:1313'
  Referrer-Policy = 'strict-origin-when-cross-origin'
  X-Content-Type-Options = 'nosniff'
  X-Frame-Options = 'DENY'
  X-XSS-Protection = '1; mode=block'
```

=== “json”

```json
{
   "headers": [
      {
         "for": "/**",
         "values": {
            "Content-Security-Policy": "script-src localhost:1313",
            "Referrer-Policy": "strict-origin-when-cross-origin",
            "X-Content-Type-Options": "nosniff",
            "X-Frame-Options": "DENY",
            "X-XSS-Protection": "1; mode=block"
         }
      }
   ]
}
```

​ 您还可以为服务器指定简单的重定向规则。 语法与Netlify类似。

​ 请注意,status200会触发URL重写,这是在SPA情况下所需要的,例如:

config/development/server.

=== “yaml”

```yaml
redirects:
- force: false
  from: /myspa/**
  status: 200
  to: /myspa/
```

=== “toml”

```toml
[[redirects]]
force = false
from = '/myspa/**'
status = 200
to = '/myspa/'
```

=== “json”

```json
{
   "redirects": [
      {
         "force": false,
         "from": "/myspa/**",
         "status": 200,
         "to": "/myspa/"
      }
   ]
}
```

​ 设置force=true将使重定向即使路径中存在现有内容也会生效。 请注意,在Hugo 0.76之前,force是默认行为,但这符合Netlify的处理方式。

404服务器错误页面 -> [[redirects]]

New in v0.103.0

​ 当运行hugo server时,默认情况下,Hugo将使用404.html模板呈现所有404错误。 请注意,如果您已经添加了一个或多个重定向到服务器配置中,则需要显式添加404重定向,例如:

config/development/server.

=== “yaml”

```yaml
redirects:
- from: /**
  status: 404
  to: /404.html
```

=== “toml”

```toml
[[redirects]]
from = '/**'
status = 404
to = '/404.html'
```

=== “json”

```json
{
   "redirects": [
      {
         "from": "/**",
         "status": 404,
         "to": "/404.html"
      }
   ]
}
```

配置标题大小写 -> titleCaseStyle

​ 设置titleCaseStyle以指定title模板函数和Hugo中自动部分标题使用的标题样式。

​ 默认情况下,Hugo遵循美联社 (Associated Press(AP))风格指南中的大写规则。 如果您想遵循芝加哥风格(Chicago Manual of Style)手册,则将titleCaseStyle设置为chicago,或将其设置为go以使用Go的惯例,即每个单词都大写。

配置环境变量

  • HUGO_NUMWORKERMULTIPLIER

    可以设置为增加或减少在Hugo中并行处理中使用的工作程序数量。 如果未设置,则将使用逻辑CPU的数量。

配置查找顺序

​ 与模板查找顺序类似,Hugo有一组默认规则,用于在站点源目录的根目录中搜索配置文件作为默认行为:

  1. ./config.toml
  2. ./config.yaml
  3. ./config.json

​ 在config文件中,您可以指导Hugo如何渲染您的站点,控制您的站点菜单,并任意定义特定于您的项目的站点范围(site-wide)参数。

示例配置

​ 以下是典型的配置文件示例。在params:下嵌套的值将填充.Site.Params变量,供模板使用:

config.

=== “yaml”

```yaml
baseURL: https://yoursite.example.com/
params:
  AuthorName: Jon Doe
  GitHubUser: spf13
  ListOfFoo:
  - foo1
  - foo2
  SidebarRecentLimit: 5
  Subtitle: Hugo is Absurdly Fast!
permalinks:
  posts: /:year/:month/:title/
title: My Hugo Site
```

=== “toml”

```toml
baseURL = 'https://yoursite.example.com/'
title = 'My Hugo Site'
[params]
  AuthorName = 'Jon Doe'
  GitHubUser = 'spf13'
  ListOfFoo = ['foo1', 'foo2']
  SidebarRecentLimit = 5
  Subtitle = 'Hugo is Absurdly Fast!'
[permalinks]
  posts = '/:year/:month/:title/'
```

=== “json”

```json
{
   "baseURL": "https://yoursite.example.com/",
   "params": {
      "AuthorName": "Jon Doe",
      "GitHubUser": "spf13",
      "ListOfFoo": [
         "foo1",
         "foo2"
      ],
      "SidebarRecentLimit": 5,
      "Subtitle": "Hugo is Absurdly Fast!"
   },
   "permalinks": {
      "posts": "/:year/:month/:title/"
   },
   "title": "My Hugo Site"
}
```

使用环境变量配置

​ 除了已经提到的三个配置选项外,可以通过操作系统环境变量定义配置键值。

​ 例如,以下命令将在类Unix系统上有效地设置站点标题:

1
$ env HUGO_TITLE="Some Title" hugo

​ 如果您使用像Netlify这样的服务部署您的站点,则这非常有用。请参阅Hugo文档中的Netlify配置文件示例

​ 名称必须以HUGO_为前缀,并且设置操作系统环境变量时必须将配置键设置为大写。

​ 要设置配置参数,请使用HUGO_PARAMS_作为前缀。

​ 如果您使用了下划线命名法,则上述方法将无法正常工作。Hugo通过HUGO之后的第一个字符确定要使用的分隔符。这允许您使用任何[允许的](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So names may contain any,not begin with a digit)分隔符来定义形式为HUGOxPARAMSxAPI_KEY=abcdefgh的环境变量。

忽略内容和数据文件的渲染 -> ignoreFiles

​ 注意:这个方法可行,但我们建议您使用更新且更强大的includeFiles和excludeFiles挂载选项。

​ 要在渲染站点时排除特定的contentdata目录中的文件,请将ignoreFiles设置为一个或多个正则表达式,以匹配绝对文件路径。

​ 要忽略以.foo.boo结尾的文件:

=== “yaml”

```yaml
ignoreFiles:
- \.foo$
- \.boo$
```

=== “toml”

```toml
ignoreFiles = ['\.foo$', '\.boo$']
```

=== “json”

```json
{
   "ignoreFiles": [
      "\\.foo$",
      "\\.boo$"
   ]
}
```

​ 通过绝对文件路径忽略一个文件:

=== “yaml”

```yaml
ignoreFiles:
- ^/home/user/project/content/test\.md$
```

=== “toml”

```toml
ignoreFiles = ['^/home/user/project/content/test\.md$']
```

=== “json”

```json
{
   "ignoreFiles": [
      "^/home/user/project/content/test\\.md$"
   ]
}
```

配置Front Matter -> [frontmatter]

配置日期

​ 日期在Hugo中很重要,您可以通过向config.toml添加frontmatter部分来配置Hugo如何为您的内容页面分配日期。

默认配置如下:

config.

=== “yaml”

```yaml
frontmatter:
  date:
  - date
  - publishDate
  - lastmod
  expiryDate:
  - expiryDate
  lastmod:
  - :git
  - lastmod
  - date
  - publishDate
  publishDate:
  - publishDate
  - date
```

=== “toml”

```toml
[frontmatter]
  date = ['date', 'publishDate', 'lastmod']
  expiryDate = ['expiryDate']
  lastmod = [':git', 'lastmod', 'date', 'publishDate']
  publishDate = ['publishDate', 'date']
```

=== “json”

```json
{
   "frontmatter": {
      "date": [
         "date",
         "publishDate",
         "lastmod"
      ],
      "expiryDate": [
         "expiryDate"
      ],
      "lastmod": [
         ":git",
         "lastmod",
         "date",
         "publishDate"
      ],
      "publishDate": [
         "publishDate",
         "date"
      ]
   }
}
```

​ 如果您的一些内容中具有非标准日期参数,您可以覆盖date的设置:

config.

=== “yaml”

```yaml
frontmatter:
  date:
  - myDate
  - :default
```

=== “toml”

```toml
[frontmatter]
  date = ['myDate', ':default']
```

=== “json”

```json
{
   "frontmatter": {
      "date": [
         "myDate",
         ":default"
      ]
   }
}
```

:default是默认设置的快捷方式。以上设置将根据需要将.Date设置为myDate中的日期值,如果不存在,则会查找datepublishDatelastmod并选择第一个有效日期。

​ 在右侧的列表中,以":“开头的值是具有特殊含义的日期处理程序(见下文)。其他的只是您的正文数据配置中日期参数的名称(大小写不敏感)。另请注意,Hugo有一些内置别名:lastmod => modifiedpublishDate => pubdatepublishedexpiryDate => unpublishdate。例如,使用front matter中的pubDate作为日期将默认分配给.PublishDate

​ 特殊日期处理程序为:

  • :fileModTime

    从内容文件的最后修改时间戳中提取日期。

例如:

config.

=== “yaml”

```yaml
frontmatter:
  lastmod:
  - lastmod
  - :fileModTime
  - :default
```

=== “toml”

```toml
[frontmatter]
  lastmod = ['lastmod', ':fileModTime', ':default']
```

=== “json”

```json
{
   "frontmatter": {
      "lastmod": [
         "lastmod",
         ":fileModTime",
         ":default"
      ]
   }
}
```

​ 上面的配置将首先尝试从front matter参数中lastmod 提取.Lastmod的值,然后再从内容文件的修改时间戳中提取日期值。最后,:default在这里不需要,但是Hugo最终会在:gitdatepublishDate中查找有效的日期。

  • :filename

    从内容文件的文件名中提取日期。例如,2018-02-22-mypage.md将提取日期2018-02-22。此外,如果slug未设置,则mypage将作为.Slug的值。

例如:

config.

=== “yaml”

```yaml
frontmatter:
  date:
  - :filename
  - :default
```

=== “toml”

```toml
[frontmatter]
  date = [':filename', ':default']
```

=== “json”

```json
{
   "frontmatter": {
      "date": [
         ":filename",
         ":default"
      ]
   }
}
```

​ 以上配置将首先尝试从文件名中提取.Date的值,然后再从front matter参数的datepublishDatelastmod中查找。

  • :git

    这是此内容文件的最后修订版的Git作者日期。这只有在设置了 --enableGitInfo 或在站点配置中设置了 enableGitInfo = true 时才会被设置。

配置其他输出格式

​ Hugo v0.20引入了将内容呈现为多种输出格式(例如JSON、AMP html或CSV)的能力。请参阅输出格式,了解如何将这些值添加到您的Hugo项目配置文件中。

配置压缩 -> [minify]

默认配置:

config.

=== “yaml”

```yaml
minify:
  disableCSS: false
  disableHTML: false
  disableJS: false
  disableJSON: false
  disableSVG: false
  disableXML: false
  minifyOutput: false
  tdewolff:
    css:
      keepCSS2: true
      precision: 0
    html:
      keepComments: false
      keepConditionalComments: true
      keepDefaultAttrVals: true
      keepDocumentTags: true
      keepEndTags: true
      keepQuotes: false
      keepWhitespace: false
    js:
      keepVarNames: false
      noNullishOperator: false
      precision: 0
    json:
      keepNumbers: false
      precision: 0
    svg:
      keepComments: false
      precision: 0
    xml:
      keepWhitespace: false
```

=== “toml”

```toml
[minify]
  disableCSS = false
  disableHTML = false
  disableJS = false
  disableJSON = false
  disableSVG = false
  disableXML = false
  minifyOutput = false
  [minify.tdewolff]
    [minify.tdewolff.css]
      keepCSS2 = true
      precision = 0
    [minify.tdewolff.html]
      keepComments = false
      keepConditionalComments = true
      keepDefaultAttrVals = true
      keepDocumentTags = true
      keepEndTags = true
      keepQuotes = false
      keepWhitespace = false
    [minify.tdewolff.js]
      keepVarNames = false
      noNullishOperator = false
      precision = 0
    [minify.tdewolff.json]
      keepNumbers = false
      precision = 0
    [minify.tdewolff.svg]
      keepComments = false
      precision = 0
    [minify.tdewolff.xml]
      keepWhitespace = false
```

=== “json”

```json
{
   "minify": {
      "disableCSS": false,
      "disableHTML": false,
      "disableJS": false,
      "disableJSON": false,
      "disableSVG": false,
      "disableXML": false,
      "minifyOutput": false,
      "tdewolff": {
         "css": {
            "keepCSS2": true,
            "precision": 0
         },
         "html": {
            "keepComments": false,
            "keepConditionalComments": true,
            "keepDefaultAttrVals": true,
            "keepDocumentTags": true,
            "keepEndTags": true,
            "keepQuotes": false,
            "keepWhitespace": false
         },
         "js": {
            "keepVarNames": false,
            "noNullishOperator": false,
            "precision": 0
         },
         "json": {
            "keepNumbers": false,
            "precision": 0
         },
         "svg": {
            "keepComments": false,
            "precision": 0
         },
         "xml": {
            "keepWhitespace": false
         }
      }
   }
}
```

配置文件缓存 -> [caches]

​ 自Hugo 0.52版本以来,您可以配置的不仅是cacheDir。这是默认配置:

=== “yaml”

```yaml
caches:
  assets:
    dir: :resourceDir/_gen
    maxAge: -1
  getcsv:
    dir: :cacheDir/:project
    maxAge: -1
  getjson:
    dir: :cacheDir/:project
    maxAge: -1
  getresource:
    dir: :cacheDir/:project
    maxAge: -1
  images:
    dir: :resourceDir/_gen
    maxAge: -1
  modules:
    dir: :cacheDir/modules
    maxAge: -1
```

=== “toml”

```toml
[caches]
  [caches.assets]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.getcsv]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getjson]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getresource]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.images]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.modules]
    dir = ':cacheDir/modules'
    maxAge = -1
```

=== “json”

```json
{
   "caches": {
      "assets": {
         "dir": ":resourceDir/_gen",
         "maxAge": -1
      },
      "getcsv": {
         "dir": ":cacheDir/:project",
         "maxAge": -1
      },
      "getjson": {
         "dir": ":cacheDir/:project",
         "maxAge": -1
      },
      "getresource": {
         "dir": ":cacheDir/:project",
         "maxAge": -1
      },
      "images": {
         "dir": ":resourceDir/_gen",
         "maxAge": -1
      },
      "modules": {
         "dir": ":cacheDir/modules",
         "maxAge": -1
      }
   }
}
```

​ 您可以在自己的config.toml中覆盖这些缓存设置。

关键字的解释

  • :cacheDir

    这是cacheDir配置选项的值,如果设置了的话(也可以通过OS环境变量HUGO_CACHEDIR设置)。如果在Netlify上,将回退到/opt/build/cache/hugo_cache/,对于其他的操作系统,将位于操作系统临时目录下的hugo_cache目录。这意味着,如果您在Netlify上运行构建,所有配置为:cacheDir的缓存都将保存并在下一次构建时恢复。对于其他的CI供应商,请阅读其文档。有关CircleCI示例,请参见此配置

  • :project

    当前Hugo项目的基本目录名称。这意味着,在默认设置中,每个项目都有单独的文件缓存,这意味着当您运行hugo --gc时,您不会触及与其他在同一台电脑上运行的Hugo项目相关的文件。

  • :resourceDir

    这是resourceDir配置选项的值。

  • maxAge

    这是缓存条目被清除之前的持续时间,-1表示永远,0有效地关闭该特定缓存。使用Go的time.Duration,所以有效值是"10s"(10秒),"10m"(10分钟)和"10h"(10小时)。

  • dir

    这是用于存储此缓存文件的绝对路径。允许的起始占位符是:cacheDir:resourceDir(见上文)。

配置格式规范

参见

5 - Configure Markup

Configure Markup

How to handle Markdown and other markup related configuration.

Configure Markup

See Goldmark for settings related to the default Markdown handler in Hugo.

Below are all markup related configuration in Hugo with their default settings:

config.

=== “yaml”

```yaml
markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false
  defaultMarkdownHandler: goldmark
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      linkifyProtocol: https
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute:
        block: false
        title: true
      autoHeadingID: true
      autoHeadingIDType: github
      wrapStandAloneImageWithinParagraph: true
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    hl_inline: false
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    noHl: false
    style: monokai
    tabWidth: 4
  tableOfContents:
    endLevel: 3
    ordered: false
    startLevel: 2
```

=== “toml”

```toml
[markup]
  defaultMarkdownHandler = 'goldmark'
  [markup.asciidocExt]
    backend = 'html5'
    extensions = []
    failureLevel = 'fatal'
    noHeaderOrFooter = true
    preserveTOC = false
    safeMode = 'unsafe'
    sectionNumbers = false
    trace = false
    verbose = false
    workingFolderCurrent = false
    [markup.asciidocExt.attributes]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      linkifyProtocol = 'https'
      strikethrough = true
      table = true
      taskList = true
      typographer = true
    [markup.goldmark.parser]
      autoHeadingID = true
      autoHeadingIDType = 'github'
      wrapStandAloneImageWithinParagraph = true
      [markup.goldmark.parser.attribute]
        block = false
        title = true
    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false
  [markup.highlight]
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ''
    hl_inline = false
    lineAnchors = ''
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    noHl = false
    style = 'monokai'
    tabWidth = 4
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2
```

=== “json”

```json
{
   "markup": {
      "asciidocExt": {
         "attributes": {},
         "backend": "html5",
         "extensions": [],
         "failureLevel": "fatal",
         "noHeaderOrFooter": true,
         "preserveTOC": false,
         "safeMode": "unsafe",
         "sectionNumbers": false,
         "trace": false,
         "verbose": false,
         "workingFolderCurrent": false
      },
      "defaultMarkdownHandler": "goldmark",
      "goldmark": {
         "extensions": {
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "linkifyProtocol": "https",
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": true
         },
         "parser": {
            "attribute": {
               "block": false,
               "title": true
            },
            "autoHeadingID": true,
            "autoHeadingIDType": "github",
            "wrapStandAloneImageWithinParagraph": true
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      },
      "highlight": {
         "anchorLineNos": false,
         "codeFences": true,
         "guessSyntax": false,
         "hl_Lines": "",
         "hl_inline": false,
         "lineAnchors": "",
         "lineNoStart": 1,
         "lineNos": false,
         "lineNumbersInTable": true,
         "noClasses": true,
         "noHl": false,
         "style": "monokai",
         "tabWidth": 4
      },
      "tableOfContents": {
         "endLevel": 3,
         "ordered": false,
         "startLevel": 2
      }
   }
}
```

See each section below for details.

Goldmark

Goldmark is from Hugo 0.60 the default library used for Markdown. It’s fast, it’s CommonMark compliant and it’s very flexible.

This is the default configuration:

config.

=== “yaml”

```yaml
markup:
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      linkifyProtocol: https
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute:
        block: false
        title: true
      autoHeadingID: true
      autoHeadingIDType: github
      wrapStandAloneImageWithinParagraph: true
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false
```

=== “toml”

```toml
[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      linkifyProtocol = 'https'
      strikethrough = true
      table = true
      taskList = true
      typographer = true
    [markup.goldmark.parser]
      autoHeadingID = true
      autoHeadingIDType = 'github'
      wrapStandAloneImageWithinParagraph = true
      [markup.goldmark.parser.attribute]
        block = false
        title = true
    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false
```

=== “json”

```json
{
   "markup": {
      "goldmark": {
         "extensions": {
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "linkifyProtocol": "https",
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": true
         },
         "parser": {
            "attribute": {
               "block": false,
               "title": true
            },
            "autoHeadingID": true,
            "autoHeadingIDType": "github",
            "wrapStandAloneImageWithinParagraph": true
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}
```

For details on the extensions, refer to this section of the Goldmark documentation

Some settings explained:

  • hardWraps

    By default, Goldmark ignores newlines within a paragraph. Set to true to render newlines as <br> elements.

  • unsafe

    By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.

  • typographer

    This extension substitutes punctuations with typographic entities like smartypants.

  • attribute

    Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets ({.myclass class="class1 class2" }) and placing it after the Markdown element it decorates, on the same line for titles and on a new line directly below for blocks.

Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.

A blockquote with a CSS class:

1
2
3
> foo
> bar
{.myclass}

There are some current limitations: For tables you can currently only apply it to the full table, and for lists the ul/ol-nodes only, e.g.:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
* Fruit
  * Apple
  * Orange
  * Banana
  {.fruits}
* Dairy
  * Milk
  * Cheese
  {.dairies}
{.list}

Note that attributes in code fences must come after the opening tag, with any other highlighting processing instruction, e.g.:

1
2
3
```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```
  • autoHeadingIDType (“github”)

    The strategy used for creating auto IDs (anchor names). Available types are github, github-ascii and blackfriday. github produces GitHub-compatible IDs, github-ascii will drop any non-Ascii characters after accent normalization, and blackfriday will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the anchorize template func.

Highlight

This is the default highlight configuration. Note that some of these settings can be set per code block, see Syntax Highlighting.

config.

=== “yaml”

```yaml
markup:
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    hl_inline: false
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    noHl: false
    style: monokai
    tabWidth: 4
```

=== “toml”

```toml
[markup]
  [markup.highlight]
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ''
    hl_inline = false
    lineAnchors = ''
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    noHl = false
    style = 'monokai'
    tabWidth = 4
```

=== “json”

```json
{
   "markup": {
      "highlight": {
         "anchorLineNos": false,
         "codeFences": true,
         "guessSyntax": false,
         "hl_Lines": "",
         "hl_inline": false,
         "lineAnchors": "",
         "lineNoStart": 1,
         "lineNos": false,
         "lineNumbersInTable": true,
         "noClasses": true,
         "noHl": false,
         "style": "monokai",
         "tabWidth": 4
      }
   }
}
```

For style, see these galleries:

For CSS, see Generate Syntax Highlighter CSS.

Table Of Contents

config.

=== “yaml”

```yaml
markup:
  tableOfContents:
    endLevel: 3
    ordered: false
    startLevel: 2
```

=== “toml”

```toml
[markup]
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2
```

=== “json”

```json
{
   "markup": {
      "tableOfContents": {
         "endLevel": 3,
         "ordered": false,
         "startLevel": 2
      }
   }
}
```

These settings only works for the Goldmark renderer:

  • startLevel

    The heading level, values starting at 1 (h1), to start render the table of contents.

  • endLevel

    The heading level, inclusive, to stop render the table of contents.

  • ordered

    Whether or not to generate an ordered list instead of an unordered list.

Markdown Render Hooks

See Markdown Render Hooks.

See Also

6 - 外部学习资源

External Learning Resources - 外部学习资源

https://gohugo.io/getting-started/external-learning-resources/

​ 关于 Hugo 的教程和书籍列表。

书籍

Hugo 实战

Hugo In Action

《Hugo 实战》是一本使用 Hugo 创建静态站点的逐步指南。您将使用一个完整的示例站点和源代码示例来学习如何构建和托管一个低维护、高性能的站点,它将为您的用户提供令人惊叹的体验,并且不需要依赖于第三方服务器。

Hugo 实战主页

使用 Hugo 构建站点

《使用 Hugo 构建站点:使用 Markdown 进行快速 Web 开发》(2020) 作者 Brian P. Hogan。

初学者教程

CloudCannon 的 Hugo 教程

逐步书面教程,教您创建 Hugo 站点的基础知识。

视频教程

另请参阅