配置文件

Hugo 的配置文件控制着站点的各种行为。本章将详细介绍配置选项和最佳实践。

配置文件格式

Hugo 支持三种配置格式：TOML、YAML 和 JSON。推荐使用 TOML 格式。

TOML 格式（推荐）

hugo.toml：

baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的博客'
theme = 'ananke'

[params]
  description = "一个技术博客"
  author = "张三"

[menu]
  [[menu.main]]
    name = "首页"
    url = "/"
    weight = 1

YAML 格式

hugo.yaml：

baseURL: https://example.org/
languageCode: zh-cn
title: 我的博客
theme: ananke

params:
  description: 一个技术博客
  author: 张三

menu:
  main:
    - name: 首页
      url: /
      weight: 1

JSON 格式

config.json：

{
  "baseURL": "https://example.org/",
  "languageCode": "zh-cn",
  "title": "我的博客",
  "theme": "ananke",
  "params": {
    "description": "一个技术博客",
    "author": "张三"
  }
}

核心配置

站点基本信息

baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的博客'
theme = 'ananke'

# 构建配置
buildDrafts = false
buildFuture = false
buildExpired = false

# 分页配置
[pagination]
  pagerSize = 10

# 摘要长度
summaryLength = 70

# 是否渲染 emoji
enableEmoji = true

# 是否使用相对 URL
relativeURLs = false

URL 配置

baseURL = 'https://example.org/'

# URL 格式配置
[permalinks]
  posts = '/:year/:month/:title/'

# 可用的占位符：
# :year - 年份 (2024)
# :month - 月份 (01)
# :monthname - 月份名称 (January)
# :day - 日期 (15)
# :weekday - 星期几 (1)
# :weekdayname - 星期名称 (Monday)
# :yearday - 年中第几天 (015)
# :section - 分区名 (posts)
# :sections - 所有分区 (posts/tech)
# :title - 文章标题
# :slug - 自定义 slug
# :filename - 文件名

多语言配置

defaultContentLanguage = 'zh'
defaultContentLanguageInSubdir = false

[languages]
  [languages.zh]
    title = '我的博客'
    languageCode = 'zh-CN'
    languageName = '中文'
    weight = 1
    contentDir = 'content/zh'
    
  [languages.en]
    title = 'My Blog'
    languageCode = 'en-US'
    languageName = 'English'
    weight = 2
    contentDir = 'content/en'
    
    [languages.en.params]
      description = 'A tech blog'

内容配置

分类法配置

[taxonomies]
  tag = 'tags'
  category = 'categories'
  author = 'authors'
  series = 'series'

# 禁用默认分类法
# disableKinds = ['taxonomy', 'term']

标记配置

[markup]
  defaultMarkdownHandler = 'goldmark'
  
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
      typographer = true
      
    [markup.goldmark.renderer]
      unsafe = true  # 允许 HTML 标签
      
  [markup.highlight]
    codeFences = true
    guessSyntax = true
    lineNos = true
    lineNumbersInTable = true
    noClasses = false
    style = 'monokai'
    
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 4
    ordered = false

输出格式配置

[outputs]
  home = ['HTML', 'RSS', 'JSON']
  section = ['HTML', 'RSS']
  taxonomy = ['HTML', 'RSS']
  term = ['HTML', 'RSS']

# 自定义输出格式
[outputFormats]
  [outputFormats.JSON]
    mediaType = 'application/json'
    baseName = 'index'
    isPlainText = true

菜单配置

简单配置

[menu]
  [[menu.main]]
    name = '首页'
    url = '/'
    weight = 1
    
  [[menu.main]]
    name = '博客'
    url = '/posts/'
    weight = 2
    
  [[menu.main]]
    name = '关于'
    url = '/about/'
    weight = 3

详细配置

[menu]
  [[menu.main]]
    identifier = 'posts'
    name = '博客文章'
    url = '/posts/'
    weight = 1
    pre = '<i class="icon-post"></i>'
    post = ''
    
  [[menu.main]]
    identifier = 'tutorials'
    name = '教程'
    url = '/tutorials/'
    weight = 2
    parent = 'posts'  # 子菜单
    
  [[menu.footer]]
    name = '隐私政策'
    url = '/privacy/'
    weight = 1

参数配置

站点参数

[params]
  description = '一个技术博客'
  author = '张三'
  email = '[email protected]'
  
  # 社交链接
  github = 'https://github.com/zhangsan'
  twitter = 'https://twitter.com/zhangsan'
  linkedin = 'https://linkedin.com/in/zhangsan'
  
  # SEO 配置
  keywords = ['技术', '编程', '博客']
  
  # 主题特定配置
  mainSections = ['posts']
  featuredImageField = 'image'
  
  # 评论系统
  [params.comments]
    enable = true
    provider = 'disqus'
    disqusShortname = 'my-blog'
    
  # 分析配置
  [params.analytics]
    enable = true
    googleAnalytics = 'G-XXXXXXXXXX'
    
  # 图片配置
  [params.image]
    width = 800
    height = 600
    quality = 85

环境特定配置

Hugo 支持根据环境加载不同的配置：

config/
├── _default/
│   ├── config.toml
│   ├── params.toml
│   └── menus.toml
├── development/
│   └── config.toml
└── production/
    └── config.toml

开发环境配置 config/development/config.toml：

baseURL = 'http://localhost:1313/'
buildDrafts = true

生产环境配置 config/production/config.toml：

baseURL = 'https://example.org/'
buildDrafts = false
minify = true

模块配置

Hugo Modules 是管理主题和依赖的现代方式。

[module]
  [module.hugoVersion]
    extended = true
    min = '0.100.0'
    max = ''
    
  [[module.imports]]
    path = 'github.com/theNewDynamic/gohugo-theme-ananke'
    disable = false
    
  [[module.imports]]
    path = 'github.com/example/my-theme'
    
    [[module.imports.mounts]]
      source = 'static'
      target = 'static'

挂载点配置

[module]
  [[module.mounts]]
    source = 'content'
    target = 'content'
    
  [[module.mounts]]
    source = 'static'
    target = 'static'
    
  [[module.mounts]]
    source = 'layouts'
    target = 'layouts'
    
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
    
  [[module.mounts]]
    source = 'content/en'
    target = 'content'
    lang = 'en'

安全配置

[security]
  [security.funcs]
    getenv = ['^HUGO_', '^CI$']
    
  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

性能配置

# 并行构建
enableGitInfo = true

# 缓存配置
[caches]
  [caches.assets]
    dir = ':resourceDir/_gen'
    maxAge = -1
    
  [caches.images]
    dir = ':resourceDir/_gen'
    maxAge = -1
    
  [caches.getcsv]
    dir = ':cacheDir/:project'
    maxAge = '12h'
    
  [caches.getjson]
    dir = ':cacheDir/:project'
    maxAge = '12h'

分页配置

[pagination]
  pagerSize = 10
  path = 'page'

Sitemap 配置

[sitemap]
  changefreq = 'weekly'
  filename = 'sitemap.xml'
  priority = 0.5

RSS 配置

[outputs]
  home = ['HTML', 'RSS']
  
[outputFormats.RSS]
  baseName = 'feed'
  mediaType = 'application/rss+xml'

完整配置示例

baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的技术博客'
theme = 'ananke'

buildDrafts = false
buildFuture = false
enableEmoji = true
enableRobotsTXT = true
summaryLength = 70

[pagination]
  pagerSize = 10

[permalinks]
  posts = '/:year/:month/:title/'

[taxonomies]
  tag = 'tags'
  category = 'categories'
  author = 'authors'

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true
  [markup.highlight]
    codeFences = true
    guessSyntax = true
    lineNos = true
    style = 'monokai'
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 4

[menu]
  [[menu.main]]
    name = '首页'
    url = '/'
    weight = 1
  [[menu.main]]
    name = '博客'
    url = '/posts/'
    weight = 2
  [[menu.main]]
    name = '关于'
    url = '/about/'
    weight = 3

[params]
  description = '分享技术心得和编程经验'
  author = '张三'
  email = '[email protected]'
  github = 'https://github.com/zhangsan'
  
  [params.comments]
    enable = true
    provider = 'giscus'
    
  [params.analytics]
    enable = true
    googleAnalytics = 'G-XXXXXXXXXX'

[outputs]
  home = ['HTML', 'RSS', 'JSON']
  section = ['HTML', 'RSS']

[sitemap]
  changefreq = 'weekly'
  priority = 0.5

[related]
  includeNewer = true
  threshold = 80
  
  [[related.indices]]
    name = 'tags'
    weight = 100
  [[related.indices]]
    name = 'categories'
    weight = 80

配置文件拆分

对于大型项目，可以将配置拆分为多个文件：

config/
└── _default/
    ├── config.toml      # 主配置
    ├── params.toml      # 参数配置
    ├── menus.toml       # 菜单配置
    ├── markup.toml      # 标记配置
    └── languages.toml   # 语言配置

config/_default/config.toml：

baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的博客'
theme = 'ananke'

config/_default/params.toml：

description = '一个技术博客'
author = '张三'

[comments]
  enable = true
  provider = 'giscus'

config/_default/menus.toml：

[[main]]
  name = '首页'
  url = '/'
  weight = 1
  
[[main]]
  name = '博客'
  url = '/posts/'
  weight = 2

小结

本章介绍了 Hugo 配置的核心知识：

支持多种配置格式，推荐使用 TOML
核心配置包括站点信息、URL、多语言等
内容配置控制分类法、标记解析等
参数配置用于自定义站点属性
可以按环境拆分配置文件

下一章将学习主题开发，掌握如何创建自定义主题。

配置文件格式​

TOML 格式（推荐）​

YAML 格式​

JSON 格式​

核心配置​

站点基本信息​

URL 配置​

多语言配置​

内容配置​

分类法配置​

标记配置​

输出格式配置​

菜单配置​

简单配置​

详细配置​

参数配置​

站点参数​

环境特定配置​

模块配置​

挂载点配置​

安全配置​

性能配置​

相关内容配置​

分页配置​

Sitemap 配置​

RSS 配置​

完整配置示例​

配置文件拆分​

小结​