Hugo 博客写作指南（二）：hugo.toml 配置详解

本文是 Hugo 博客写作指南系列的第二篇，详细介绍 hugo.toml 配置文件的各项参数和使用方法。

hugo.toml 是 Hugo 站点的主配置文件，控制着整个博客的行为和外观。本文将基于 ChangAn 主题，详细解析每个配置项的作用。

基础站点配置

1. 站点基本信息

baseURL = 'https://changan.icecome.com/'
languageCode = 'zh-cn'
title = '长安的个人博客'
theme = 'changan'

参数说明：

参数	作用	示例
`baseURL`	网站的完整 URL	`'https://example.com/'`
`languageCode`	网站语言代码	`'zh-cn'`, `'en-us'`
`title`	网站标题	`'我的长安的个人博客'`
`theme`	使用的主题名称	`'changan'`

注意事项：

baseURL 必须以 / 结尾
部署到生产环境前记得修改 baseURL
theme 必须与 themes/ 目录下的主题文件夹名称一致

2. 分页配置

[pagination]
  pagerSize = 10

参数说明：

pagerSize：每页显示的文章数量
适用于首页、分类页、标签页等

建议值：

10：适合内容丰富的博客
5：适合文章较长的博客
20：适合文章较短的博客

主题参数配置 [params]

[params] 部分包含 ChangAn 主题的自定义配置，控制网站的外观和功能。

3. 站点描述和作者信息

[params]
  description = '长安的个人博客'
  author = '长安'
  motto = '记录生活，分享知识'
  intro = 'Clean, Cute, Fast.'

参数说明：

参数	作用	显示位置
`description`	站点描述	SEO、首页 meta 标签
`author`	作者名称	文章页面、版权信息
`motto`	座右铭	首页、关于页面
`intro`	简介	首页横幅区域

自定义建议：

description：50-160 个字符，包含关键词
author：使用真实姓名或笔名
motto：简短有力，体现个人特色
intro：一句话介绍博客定位

4. 头像配置

[params]
  avatar = '/images/default-avatar.webp'

参数说明：

avatar：站点头像图片路径
显示位置：首页、导航栏、关于页面

图片要求：

格式：推荐使用 WebP 或 PNG
尺寸：建议 256x256 像素或更大
位置：放在 static/images/ 目录下

更换头像步骤：

准备头像图片（建议正方形）
将图片放到 static/images/ 目录
修改配置：avatar = '/images/your-avatar.webp'

5. 一言配置

[params]
  yiyan = '当第一颗卫星飞向大气层外，我们便以为自己终有一日会征服宇宙。'

参数说明：

yiyan：首页底部显示的名言/句子
来源：可以来自一言 API 或自定义

自定义建议：

使用喜欢的名人名言
使用自己创作的句子
定期更新保持新鲜感

6. 时间配置

[params]
  since = '2026'
  startTime = '2026-03-01T00:00:00Z'
  dateFormat = '2006-01-02'

参数说明：

参数	作用	格式
`since`	建站年份	`'YYYY'`
`startTime`	建站时间	ISO 8601 格式
`dateFormat`	日期显示格式	Go 时间格式

注意事项：

since 用于显示版权年份
startTime 用于计算运行时间
dateFormat 使用 Go 的参考时间：2006-01-02 15:04:05

7. 交互配置

[params]
  scrollThreshold = 300
  searchDebounce = 300
  animationDuration = 300
  readingSpeed = 400

参数说明：

参数	作用	单位	建议值
`scrollThreshold`	返回顶部按钮显示的滚动阈值	像素	300
`searchDebounce`	搜索输入防抖时间	毫秒	300
`animationDuration`	动画持续时间	毫秒	300
`readingSpeed`	阅读速度（用于计算阅读时间）	字/分钟	400

自定义建议：

一般不需要修改这些值
如果觉得返回顶部出现太早，可以增加 scrollThreshold
如果觉得动画太慢，可以减少 animationDuration

8. 社交链接配置

[[params.socials]]
  name = 'QQ'
  icon = 'icon-qq'
  url = 'https://wpa.qq.com/msgrd?v=3&uin=123456&site=qq&menu=yes'
[[params.socials]]
  name = 'Email'
  icon = 'icon-mail'
  url = 'mailto:your@email.com'
[[params.socials]]
  name = 'Weibo'
  icon = 'icon-weibo'
  url = 'https://weibo.com'
[[params.socials]]
  name = 'Github'
  icon = 'icon-github'
  url = 'https://github.com/changan0827'

参数说明：

参数	作用	说明
`name`	平台名称	显示为提示文字
`icon`	图标类名	使用 iconfont 图标
`url`	链接地址	个人主页或联系方式

支持的社交平台图标：

icon-qq - QQ
icon-weibo - 微博
icon-github - GitHub
icon-mail - 邮箱
icon-wechat - 微信
icon-zhihu - 知乎
icon-bilibili - B 站
icon-douban - 豆瓣
icon-telegram - Telegram
icon-twitter / icon-x - Twitter/X

添加社交链接步骤：

复制一个 [[params.socials]] 块
修改 name、icon、url
保存并重新构建

示例 - 添加微信：

[[params.socials]]
  name = 'WeChat'
  icon = 'icon-wechat'
  url = 'javascript:;'  # 可以配合弹窗显示二维码

9. 主菜单配置

[menu]
  [[menu.main]]
    identifier = 'home'
    name = '首页'
    url = '/'
    weight = 1
    [menu.main.params]
      icon = 'icon-pantone'
  [[menu.main]]
    identifier = 'archives'
    name = '归档'
    url = '/archives/'
    weight = 2
    [menu.main.params]
      icon = 'icon-archive'
  [[menu.main]]
    identifier = 'tags'
    name = '标签'
    url = '/tags/'
    weight = 3
    [menu.main.params]
      icon = 'icon-hashtag'
  [[menu.main]]
    identifier = 'links'
    name = '友链'
    url = '/links/'
    weight = 4
    [menu.main.params]
      icon = 'icon-hearts'
  [[menu.main]]
    identifier = 'about'
    name = '关于'
    url = '/about/'
    weight = 5
    [menu.main.params]
      icon = 'icon-ghost'

参数说明：

参数	作用	说明
`identifier`	菜单唯一标识	用于内部引用
`name`	菜单显示名称	导航栏显示的文字
`url`	菜单链接	页面路径
`weight`	菜单排序	数值越小越靠前
`icon`	菜单图标	iconfont 图标类名

可用图标：

icon-pantone - 首页
icon-archive - 归档
icon-hashtag - 标签
icon-hearts - 友链
icon-ghost - 关于
icon-contacts-book - 文章
icon-folder - 分类

添加自定义菜单：

[[menu.main]]
  identifier = 'projects'
  name = '项目'
  url = '/projects/'
  weight = 6
  [menu.main.params]
    icon = 'icon-rocket'

注意事项：

url 必须以 / 开头和结尾
weight 决定显示顺序
移动端菜单会自动适配

Markdown 渲染配置 [markup]

10. 代码高亮配置

[markup]
  [markup.highlight]
    codeFences = true
    lineNos = false
    style = 'github'

参数说明：

参数	作用	可选值
`codeFences`	启用代码围栏	`true`/`false`
`lineNos`	显示行号	`true`/`false`
`style`	高亮主题	见下方说明

支持的高亮主题：

github - GitHub 风格（浅色）
github-dark - GitHub 深色风格
monokai - Monokai 经典主题
dracula - Dracula 主题
one-dark - One Dark 主题
native - 原生风格

查看完整主题列表：

hugo config | grep highlight

建议：

ChangAn 主题使用自定义的代码块样式
style 设置影响语法高亮的颜色

11. Goldmark 渲染器配置

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = false

参数说明：

unsafe：是否允许渲染原始 HTML
false：更安全，但不支持 HTML 标签
true：支持 HTML，但需要注意 XSS 风险

使用场景：

写技术文章建议设置为 false
需要自定义 HTML 时设置为 true

12. 目录生成配置

[markup]
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 4
    ordered = false

参数说明：

参数	作用	说明
`startLevel`	目录起始级别	`2` 表示从 `##` 开始
`endLevel`	目录结束级别	`4` 表示到 `####` 结束
`ordered`	是否使用有序列表	`false` 为无序列表

建议：

一般使用默认值即可
文章结构清晰时目录更有用

分类法配置 [taxonomies]

13. 自定义分类法

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

参数说明：

tag：标签分类法的 URL 路径
category：分类分类法的 URL 路径

默认行为：

标签页面：/tags/标签名/
分类页面：/categories/分类名/

自定义示例：

[taxonomies]
  tag = 'topic'      # 标签页面变为 /topic/
  category = 'type'  # 分类页面变为 /type/

输出配置 [outputs]

14. 页面输出格式

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

参数说明：

页面类型	输出格式	说明
`home`	HTML, RSS, JSON	首页输出三种格式
`section`	HTML	分类页面只输出 HTML
`taxonomy`	HTML	标签页面只输出 HTML

用途：

HTML：网页浏览
RSS：RSS 订阅
JSON：搜索功能使用（生成 /index.json）

注意事项：

不要删除 JSON 输出，否则搜索功能会失效
RSS feed 地址：/index.xml

Front Matter 配置 [frontmatter]

15. 最后修改时间配置

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

参数说明：

定义 lastmod 的获取优先级
lastmod：Front Matter 中的 lastmod 字段
:fileModTime：文件修改时间
:default：使用默认值

效果：

优先使用 Front Matter 中的 lastmod
如果没有，则使用文件修改时间
最后使用 Hugo 的默认行为

完整配置示例

baseURL = 'https://example.com/'
languageCode = 'zh-cn'
title = '我的长安的个人博客'
theme = 'changan'

[pagination]
  pagerSize = 10

[params]
  description = '记录生活，分享知识'
  author = '你的名字'
  motto = '学无止境'
  intro = '欢迎来到我的博客'
  avatar = '/images/avatar.webp'
  yiyan = '知识就是力量'
  since = '2026'
  startTime = '2026-03-01T00:00:00Z'
  dateFormat = '2006-01-02'
  scrollThreshold = 300
  searchDebounce = 300
  animationDuration = 300
  readingSpeed = 400
  
  [[params.socials]]
    name = 'Github'
    icon = 'icon-github'
    url = 'https://github.com/yourname'
  [[params.socials]]
    name = 'Email'
    icon = 'icon-mail'
    url = 'mailto:your@email.com'

[menu]
  [[menu.main]]
    identifier = 'home'
    name = '首页'
    url = '/'
    weight = 1
    [menu.main.params]
      icon = 'icon-pantone'
  [[menu.main]]
    identifier = 'archives'
    name = '归档'
    url = '/archives/'
    weight = 2
    [menu.main.params]
      icon = 'icon-archive'

[markup]
  [markup.highlight]
    codeFences = true
    lineNos = false
    style = 'github'
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = false
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 4
    ordered = false

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

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

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

配置验证

修改配置后，可以使用以下命令验证：

# 查看完整配置
hugo config

# 本地预览
hugo server -D

# 构建站点
hugo --gc --minify

小结

本文详细介绍了 hugo.toml 的各项配置，包括：

✅ 基础配置： baseURL、title、theme
✅ 主题参数： 作者、头像、社交链接
✅ 菜单配置： 导航栏设置
✅ 渲染配置： Markdown、代码高亮
✅ 输出配置： HTML、RSS、JSON

合理配置这些参数可以让你的博客更加个性化和专业化。

上一篇： Hugo 博客写作指南（一）：Front Matter 基础属性详解

下一篇： Hugo 博客写作指南（三）：Markdown 基础用法

相关文章：