Hugo配置文件说明

Hugo的配置文件支持.yaml、.toml和.json格式，我使用的是.yaml格式，本文以.yaml格式示例。

站点配置文件config.yaml可以直接放在站点根目录，但更好的文件组织方式是将配置文件统一放在配置文件目录中。

Hugo 0.110.0版本开始，站点配置文件的名称更改为hugo.yaml，但也同时支持config.yaml。

Hugo配置文件目录结构

配置文件目录结构如下：

├── config
│   ├── _default
│   │   ├── hugo.yaml
│   │   ├── languages.yaml
│   │   ├── menus.en.yaml
│   │   ├── menus.zh.yaml
│   │   └── params.yaml
│   ├── production
│   │   ├── hugo.yaml
│   │   └── params.yaml
│   └── staging
│       ├── hugo.yaml
│       └── params.yaml

配置文件功能说明：

  • hugo.yaml：站点配置文件；
  • languages.yaml：语言配置文件，多语言站点才需要用到；
  • menus.zh.yaml：中文菜单配置文件，非多语言站点只需要menus.yaml即可；
  • params.yaml：主题需要用到的参数配置文件；

配置文件目录说明：

  • _default：无论是生产环境还是开发环境，都会使用这个目录中的配置文件；
  • production：生产环境用到的配置文件，将与_default中的配置文件合并；
  • staging：暂存环境配置文件，一般用不到；

以一个简单的场景需求说明：

当我们需要在params.yaml中配置百度统计，但不希望本地测试时加载百度统计代码，则可以将对应参数写入到production/params.yaml。

使用hugo命令生成站点时(即生产环境)，会使用production/params.yaml覆盖_default中的设置。因此，可以将_defautl看作是所有环境都需要用到的参数配置。

而使用hugo server命令则只加载_default中配置文件。要使用staging则需要以下命令：

hugo --environment staging

站点配置文件hugo.yaml常用参数说明

  • archetypeDir：指定文章模板目录。默认：archetypes；
  • assetDir：指定资源目录。存放需要Hugo Pipes处理的文件，比如需要编译的Sass或Less等。默认：assets；
  • baseURL：网站地址，如：https://www.beizigen.com/
  • buildDrafts：值为true时，生成站点时将包含草稿。默认为false；
  • canonifyURLs：生成站点时将相对路径转为绝对路径，只有使用Hugo变量或函数获取的URL才会被转换；
  • cleanDestinationDir：生成站点时，删除static目录中找不到的文件。默认为false；
  • contentDir：指定内容目录。默认：content；
  • copyright：页脚版权信息；
  • dataDir：指定data目录。存放其他配置文件，通常为JSON、YAML或TOML格式；
  • defaultContentLanguage：指定默认内容语言。只有多语言站点才需要用到，content目录中可以创建多个语言目录，放置不同语言的文章。默认：en；
  • defaultContentLanguageInSubdir：指定默认语言内容子目录，例如：content/zh；
  • disableAliases：禁用别名。默认为false；
  • disableHugoGeneratorInject：默认Hugo会生成一个meta标签，说明页面由Hugo生成，设置为true禁用；
  • disableKinds：禁用指定类型的页面。如：page、home、section、taxonomy、term、RSS、sitemap、robotsTXT、404；
  • disableLiveReload：开发环境中，Hugo会在页面中插入一个JS脚本，当源码有变更时，浏览器预览页面会自动刷新。设置为true可禁用；
  • disablePathToLower：值为true时，将禁用URL转换为小写；
  • enableEmoji：值为true时激活Emoji表情功能。默认为false；
  • enableInlineShortcodes：值为true时激活短代码功能。默认为false；
  • enableRobotsTXT：值为true时，将生成robots.txt文件。默认为false；
  • hasCJKLanguage：值为true时，将自动检测中文。默认为false。如果使用Hugo字符截断函数，需要将该参数设置为true，否则截断的字符数量不能达到预期；
  • imaging：图像处理配置；
  • languages：可以配置不同语言对应URL，只有多语言站点才需要用到；
  • markup：Markdown处理程序的配置；
  • menus：配置菜单，推荐使用单独的菜单配置文件来配置；
  • paginate：列表页显示的文章数量，超过这个数量则翻页；
  • paginatePath：分页路径名称，默认：page；
  • permalinks：重写URL规则；
  • publishDir：指定生成的站点文件存放目录。默认：public；
  • related：相关文章配置；
  • rssLimit：RSS输出的文章数量，默认为输出所有文章；
  • sitemap：站点地图配置；
  • summaryLength：摘要长度；
  • taxonomies：分类法；
  • theme：指定要使用的主题名称；
  • timeout：生成内容页面超时时间。默认：30s；
  • timeZone：指定时区；
  • title：网站标题。如：背字根；
  • uglyURLs：值为true时，将使用.html后缀这样的URL格式。默认为false；

菜单配置文件menus.yaml

一般网站导航菜单分主导航和页脚次导航，一个简单的示例如下：

main:
- identifier: home
  name: 首页
  url: /
  weight: 10

- identifier: develop
  name: 开发
  url: /category/develop/
  weight: 20

footer:
- identifier: qcloud
  name: 托管于良心云
  url: https://curl.qcloud.com/0hUzGtOR

主题调用示例：

{{- range .Site.Menus.main -}}
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
{{- end }}

其他参数配置文件params.yaml

params.yaml配置主题自定义参数，例如：

profiles: 一个热爱Web开发的大男孩
dateFormat: 2006年1月2日
baiduAnalytics: a432dfedcf3bdca5aa29494e430c634e

主题调用示例：

<p>{{ .Site.Params.profiles }}</p>

多语言配置languages.yaml

多语言站点配置文件languages.yaml示例：

en:
  title: My blog
  weight: 1
  LanguageName: English
  contentDir: content/en
  params:
    linkedin: https://linkedin.com/whoever

zh:
  title: 我的博客
  weight: 2
  LanguageName: 中文简体
  contentDir: content/zh
  params:
    linkedin: https://linkedin.com/zh/whoever

以上配置访问站点默认显示英语，访问路径/zh显示为中文。

还可以使用baseURL参数为不同语言指定不同域名：

en:
  baseURL: https://www.beizigen.com
zh:
  baseURL: https://zh.beizigen.com

这将在public中生成语言目录：

public
├── en
└── zh
阿里云