配置参考
本文档为 Hugo 网站项目提供所有配置选项的详细参考。
Hugo 配置
主配置文件（config/_default/config.toml）
基本设置
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
baseURL | 字符串 | "https://jimmysong.io" | 网站基础 URL |
title | 字符串 | "Jimmy Song" | 浏览器标签显示的网站标题 |
summaryLength | 整数 | 100 | 内容摘要的字数 |
metaDataFormat | 字符串 | "yaml" | 前置元数据格式（yaml/toml/json） |
hasCJKLanguage | 布尔值 | true | 启用中日韩语言支持 |
DefaultContentLanguage | 字符串 | "zh" | 网站默认语言 |
disableLanguages | 数组 | [] | 禁用的语言列表 |
pygmentsUseClasses | 布尔值 | true | 语法高亮使用 CSS 类 |
enableGitInfo | 布尔值 | true | 启用页面的 Git 信息 |
搜索配置
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
gcs_engine_id | 字符串 | "012737790962522169780:fd1izxsfgrs" | Google 自定义搜索引擎 ID |
内容处理
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
ignoreFiles | 数组 | 见下方 | 构建时忽略的文件模式 |
默认忽略模式：
ignoreFiles = [
".*/book/.*/image-caches/.*",
".*/book/.*/image-caches$",
".*/book/.*/[Ss][Uu][Mm][Mm][Aa][Rr][Yy]\\.md$",
".*/book/.*/[Rr][Ee][Aa][Dd][Mm][Ee]\\.md$"
]
站点参数（params 部分）
品牌相关
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
brand_icon | 字符串 | "fas fa-terminal" | 站点品牌 FontAwesome 图标 |
header_title | 字符串 | "Jimmy Song" | 页眉显示的标题 |
description | 字符串 | "宋净超的博客" | SEO 用站点描述 |
author | 字符串 | "Jimmy Song" | 站点作者名称 |
联系方式
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
email | 字符串 | "[email protected]" | 联系邮箱 |
wechat | 字符串 | "jimmysongio" | 微信号 |
contact_form_action | 字符串 | "https://formspree.io/mpzdzdbj" | 表单提交地址 |
分析与追踪
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
google_analytics_id | 字符串 | "UA-XXXXXXXXX-X" | Google Analytics 跟踪 ID |
enable_comment | 布尔值 | true | 启用评论系统 |
enableAdSense | 布尔值 | false | 启用 Google AdSense |
AdSenseClientID | 字符串 | "ca-pub-XXXXXXXXXXXXXXXX" | AdSense 客户端 ID |
UI 功能
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
anchored | 布尔值 | true | 标题添加锚点链接 |
top_header | 布尔值 | false | 显示顶部页眉栏 |
top_header_content | 字符串 | '站内搜索请按组合键 ⌘/CTRL + K' | 顶部页眉提示信息 |
图片与媒体
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
section_header_image | 字符串 | "images/backgrounds/circle.svg" | 默认分区头部背景图 |
default_banner | 字符串 | "images/banner/default.webp" | 默认横幅图片 |
images_repo_domain | 字符串 | "https://jimmysong.io/" | 图片资源域名 |
构建配置
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
sourceDir | 字符串 | "content" | 内容源目录 |
baidu_map_api_key | 字符串 | "YOUR_BAIDU_MAP_API_KEY" | 百度地图 API 密钥 |
构建设置
PostCSS
[build]
postCSS = ["postcss.config.js"]
分页
[pagination]
pagerSize = 10
图片处理
[imaging]
resampleFilter = "lanczos"
quality = 75
Markup 配置
Goldmark（Markdown 解析器）
[markup.goldmark.renderer]
unsafe = true
[markup.goldmark.parser]
wrapStandAloneImageWithinParagraph = false
[markup.goldmark.parser.attribute]
block = true
image = true
语法高亮
[markup.highlight]
codeFences = true
guessSyntax = false
hl_Lines = ""
lineNoStart = 1
lineNos = false
lineNumbersInTable = true
noClasses = true
style = "github"
tabWidth = 4
目录
[markup.tableOfContents]
endLevel = 4
ordered = false
startLevel = 2
分类法
[taxonomies]
category = "categories"
tag = "tags"
语言配置
中文（默认）
[languages.zh]
languageName = "中文"
weight = 1
languageCode = "zh"
contentDir = "content/zh"
[languages.zh.outputs]
home = ["HTML", "RSS", "JSON"]
[languages.zh.params]
home = "主页"
title = "Jimmy Song - 专注于探索后 Kubernetes 时代的云原生新范式"
copyright = "© 2017-2025 Jimmy Song 保留所有权利"
address = "中国，北京"
英文
[languages.en]
languageName = "English"
weight = 2
languageCode = "en-us"
contentDir = "content/en"
[languages.en.outputs]
home = ["HTML", "RSS", "JSON"]
[languages.en.params]
home = "Home"
header_title = "Jimmy Song"
copyright = "© 2017-2025 Jimmy Song All Right Reserved"
description = "Jimmy Song's Blog"
address = "Beijing, China"
通知系统
两种语言都支持通知系统：
[languages.zh.params.notification]
enabled = false
message = "年度重大更新，查看详情。"
title = "网站更新"
type = "info"
positionClass = "toast-bottom-right"
showDuration = 300
hideDuration = 1000
timeOut = 5000
extendedTimeOut = 1000
expiryDuration = 24
showOnMobile = true
enableClickRedirect = true
redirectUrl = "/notice/site-major-update-202506/"
插件配置（config/_default/params.toml）
仓库设置
[repository]
url = "https://github.com/rootsongjc/website"
branch = "main"
搜索配置
[search]
enable = true
min_length = 1
threshold = 0.3
provider = "wowchemy"
CSS 插件
加载的 CSS 插件包括：
- Bootstrap (
plugins/bootstrap/bootstrap.min.css) - FontAwesome v6 (
plugins/fontawesome/v6/css/) - TOC Bot (
plugins/tocbot/tocbot.css) - Slick Carousel (
plugins/slick/slick.css) - Bigger Picture (
plugins/bigger-picture/bigger-picture.css) - NoUI Slider (
plugins/nouislider/nouislider.min.css)
JavaScript 插件
加载的 JavaScript 插件包括：
- Popper.js (
plugins/popper/popper.min.js) - Bootstrap (
plugins/bootstrap/bootstrap.min.js) - Slick Carousel (
plugins/slick/slick.min.js) - Filterizr (
plugins/filterizr/jquery.filterizr.min.js) - Fuse.js 搜索 (
plugins/search/fuse.min.js) - Mark.js (
plugins/search/mark.js) - Hex MD5 (
plugins/hex_md5/hex_md5.js) - Anchor.js (
plugins/anchor/anchor.min.js) - TOC Bot (
plugins/tocbot/tocbot.min.js) - Bigger Picture (
plugins/bigger-picture/bigger-picture.min.js) - NoUI Slider (
plugins/nouislider/nouislider.min.js)
预加载器
[preloader]
enable = false
preloader = "images/preloader.gif"
广告
[ad]
enable = false
title = ""
subtitle = "[极客时间 VIP](https://time.geekbang.org/hybrid/next/svip/home?utm_source=wechat&utm_content=Jimmy-0905&utm_term=wechat-Jimmy-0905)"
description = "带你一站解锁 340+ 门专栏、视频课"
author = "专属口令「1299-300」：Jimmy9999"
image = "/images/ads/03-geekbang.png"
Google 地图
[map]
enable = false
gmap_api = "https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_MAPS_API_KEY"
map_latitude = "51.5223477"
map_longitude = "-0.1622023"
map_marker = "images/marker.png"
菜单配置
主导航（config/_default/menus.en.toml）
菜单按语言配置。主导航包括：
- 关于 (
/about) - 个人信息 - 博客 (
/blog) - 博客文章 - 探索（下拉菜单）
- 分类 (
/categories/) - 标签 (
/tags/) - 高级搜索 (
/search/) - 开源工具 (
/oss/) - 旅行 (
/travel/) - 旅行内容 - 新闻 (
/notice) - 新闻与公告 - 联系 (
/contact) - 联系方式
页脚链接
- 高级搜索
- 幻灯片分享
- 博文标签
- Awesome Cloud Native（外部链接）
书籍链接
- Envoy 基础（外部课程）
- Istio 基础（外部课程）
环境变量
可用的环境变量如下：
| 变量 | 说明 | 默认值 |
|---|---|---|
HUGO_ENV | Hugo 环境（development/production） | development |
NODE_ENV | Node.js 环境 | development |
自定义配置
前置元数据默认值
内容文件支持以下前置元数据变量：
通用变量
title- 页面标题description- SEO 用页面描述date- 发布时间lastmod- 最后修改时间draft- 草稿状态（true/false）weight- 排序权重categories- 内容分类tags- 内容标签author- 内容作者image- 特色图片banner- 横幅图片
博客专用变量
type- 内容类型（如 blog、book、notice 等）subtitle- 博文副标题summary- 自定义摘要toc- 是否启用目录comment- 是否启用评论
书籍专用变量
book- 书籍标识chapter- 章节号weight- 章节排序权重
自定义短代码配置
部分短代码可通过前置元数据配置：
Markmap 配置
markmap:
initialExpandLevel: 2
colorFreezeLevel: 3
duration: 500
性能配置
图片优化
图片自动优化，设置如下：
- 重采样滤镜：Lanczos
- 质量：75%
- 懒加载：启用
- WebP 转换：自动
缓存
- 静态资源：长时间缓存
- 图片：处理并缓存
- CSS/JS：压缩并缓存
安全配置
内容安全策略
站点实现 CSP 安全头：
- 脚本来源：本站及可信 CDN
- 样式来源：本站及内联样式
- 图片来源：本站及可信域名
- 框架来源：仅限可信域名
HTTPS 配置
- 强制 HTTPS：启用
- HSTS：启用，最大时长
- 证书：Let's Encrypt 自动续期