头像 余温Gueen
头像
余温Gueen
-- : -- : --
切换主题色
-- : -- : --
博客 hugo-teek +3 主题切换多主题配置说明 3320 字 14 分钟 -- 次

切换主题风格说明

最后更新于:

🎨 主题切换概述

Hugo-Teek 项目支持多主题切换，目前内置 3 款主题，每款主题拥有独立的布局风格和功能特性。通过修改配置文件中的 theme 字段，即可一键切换站点的整体视觉风格。

✨ 多主题特性

🚀 核心能力

  • 🎨 一键切换：修改一个配置字段即可更换整站主题
  • 📦 独立配置：每款主题拥有独立的参数配置文件
  • ⚙️ 自动合并：构建时自动合并通用配置与主题专属配置
  • 🔍 智能适配：搜索、评论等功能根据主题配置自动启用/禁用

🏗️ 配置架构

  • 通用配置：user-configuration/hugo.toml（站点基础设置）
  • 主题配置：user-configuration/themes/{主题名}/*.toml（主题专属参数）
  • 插件配置：user-configuration/teek-plugins/*.toml（所有主题共用）
  • 合并输出：hugo-teek-site/config/_default/*.toml（构建时自动生成）

📦 内置主题一览

主题对比总览

主题风格布局适用场景
hugo-teek功能丰富博客多列可调宽度功能齐全的博客 / 文档站
hugo-doc毛玻璃个人品牌单页分区个人作品集 / 品牌展示
hugo-simple简约暗黑卡片单列无侧边栏极简博客 / 专注写作

hugo-teek — 功能丰富博客主题

📝 hugo-teek 特性

  • 🏠 多种布局模式：支持 bothWidthAdjustable 等多种侧边栏布局
  • 🔍 FlexSearch 全文搜索：内置搜索索引生成和前端搜索
  • 💬 Twikoo 评论系统：一键集成评论功能
  • 📱 响应式设计：完美适配桌面端和移动端
  • 🌙 暗色模式：支持明暗主题自动切换
  • 📋 侧边栏卡片：博主信息、分类、标签、最近评论等
1# theme.toml 概要信息
2name = "Hugo Teek"
3description = "A feature-rich Hugo theme migrated from VitePress Teek theme"
4tags = ["blog", "responsive", "dark-mode", "algolia", "comment"]
5min_version = "0.120.0"

hugo-doc — 毛玻璃个人品牌主题

📝 hugo-doc 特性

  • 🪟 毛玻璃 UI：Glassmorphism 设计风格，视觉通透
  • 👤 个人品牌展示：Hero 区域、技能展示、项目作品集
  • 📄 文档区域：支持展示最新文章列表
  • 🎭 角色设定：支持自定义角色、问候语、简介
  • 📱 响应式设计：完美适配各种屏幕尺寸
1# theme.toml 概要信息
2name = "Hugo Doc"
3description = "A glassm-inspired Hugo documentation and personal brand theme"
4tags = ["documentation", "portfolio", "glassmorphism", "responsive", "blog"]
5min_version = "0.150.0"

hugo-simple — 简约暗黑卡片主题

📝 hugo-simple 特性

  • 🌑 纯黑背景：沉浸式暗色阅读体验
  • 🃏 卡片式布局：文章以卡片形式展示
  • 🎨 多配色方案：支持 pure、warm、eye、cool 等色彩风格
  • 📂 下拉菜单：支持多级导航下拉菜单
  • ⚡ 轻量极速：精简的代码结构，加载速度快
1# theme.toml 概要信息
2name = "Hugo Simple"
3description = "一个简约优雅的 Hugo 博客主题，纯黑背景，卡片式布局"
4tags = ["blog", "simple", "dark", "minimal", "responsive", "card-layout"]
5min_version = "0.150.0"

📁 配置文件路径

核心配置文件

主题切换涉及的核心配置文件路径如下：

1# user-configuration/hugo.toml
2# 站点基础配置，包含 theme 字段
3# 这是切换主题的主要修改文件
1# user-configuration/themes/{主题名}/
2# 每款主题拥有独立的配置目录
3# 包含 params.toml、menus.toml、module.toml 等
1# user-configuration/teek-plugins/*.toml
2# 所有主题共用的插件配置
3# 评论、菜单、站点信息等

目录结构总览

 1user-configuration/
 2├── hugo.toml                    # ◀️ 站点配置（theme 字段在此）
 3├── teek-plugins/                # ◀️ 通用插件配置（所有主题共用）
 4│   ├── author.toml
 5│   ├── menus.toml
 6│   ├── services.toml
 7│   └── ...
 8└── themes/                      # ◀️ 主题专属配置
 9    ├── hugo-teek/               # ◀️ hugo-teek 主题配置
10    │   ├── params.toml
11    │   ├── menus.toml
12    │   ├── module.toml
13    │   ├── homepage.toml
14    │   ├── sections.toml
15    │   ├── services.toml
16    │   └── teektools.toml
17    ├── hugo-doc/                # ◀️ hugo-doc 主题配置
18    │   ├── params.toml
19    │   ├── menus.toml
20    │   └── module.toml
21    └── hugo-simple/             # ◀️ hugo-simple 主题配置
22        ├── params.toml
23        ├── menus.toml
24        └── module.toml

📝 切换主题步骤

方式一：修改配置文件（推荐）

1# 编辑 user-configuration/hugo.toml
2# 将 theme 字段修改为目标主题名
3
4theme = 'hugo-teek'       # ◀️ 功能丰富博客主题
1# 编辑 user-configuration/hugo.toml
2# 将 theme 字段修改为目标主题名
3
4theme = 'hugo-doc'        # ◀️ 毛玻璃个人品牌主题
1# 编辑 user-configuration/hugo.toml
2# 将 theme 字段修改为目标主题名
3
4theme = 'hugo-simple'     # ◀️ 简约暗黑卡片主题

⚠️ 注意事项

修改 theme 字段后，需要重新启动开发服务器才能生效。构建工具会自动：
1️⃣ 合并通用配置与主题专属配置
2️⃣ 根据主题配置决定是否启用搜索等功能
3️⃣ 加载对应的布局模板和静态资源

方式二：命令行指定主题（临时覆盖）

如果不修改配置文件，也可以通过 Makefile 参数临时指定主题：

1# 通过 THEME 参数临时指定主题，不影响配置文件
2make dev THEME=hugo-doc
3
4# 或者指定 hugo-simple
5make dev THEME=hugo-simple
6
7# 构建生产版本时也可以指定
8make build THEME=hugo-doc
1# 自动从配置文件检测主题
2# 读取 user-configuration/hugo.toml 中的 theme 字段
3make dev

完整切换流程

 1📋 主题切换完整步骤：
 2
 31️⃣ 编辑 user-configuration/hugo.toml
 4   → 修改示例：theme = 'hugo-teek' 改为 theme = 'hugo-doc'
 5
 62️⃣ （可选）编辑主题专属配置
 7   → 编辑 user-configuration/themes/{主题名}/params.toml
 8   → 自定义主题参数、博主信息、菜单等
 9
103️⃣ 启动开发服务器
11   → 运行 make dev
12   → 或 make dev THEME=主题名（临时覆盖）
13
144️⃣ 预览效果
15   → 访问 http://localhost:8090
16   → 确认主题切换成功
17
185️⃣ 构建生产版本
19   → 运行 make build

⚙️ 主题专属配置详解

hugo-teek 主题配置

hugo-teek 是功能最丰富的主题，配置项较多：

 1# user-configuration/themes/hugo-teek/params.toml
 2
 3layoutMode = 'bothWidthAdjustable'   # ◀️ 布局模式：双侧边栏可调宽度
 4
 5[blogger]
 6  name = '余温Gueen'                  # ◀️ 博主名称
 7  slogan = '明心静性，爱自己'           # ◀️ 个性签名
 8  avatar = 'https://xxx/avatar.avif'  # ◀️ 头像地址
 9  shape = 'circle-rotate'             # ◀️ 头像形状：circle-rotate / square / rounded
10  backgroundImage = 'https://xxx/bg.avif'  # ◀️ 卡片背景图
 1# user-configuration/themes/hugo-teek/params.toml
 2
 3[search]
 4  enabled = true              # ◀️ 启用 FlexSearch 全文搜索
 5  provider = "flexsearch"     # ◀️ 搜索引擎
 6
 7[appreciation]
 8  enabled = true              # ◀️ 启用赞赏功能
 9  alipayQR = 'https://xxx'    # ◀️ 支付宝二维码
10  wechatQR = 'https://xxx'    # ◀️ 微信二维码

hugo-doc 主题配置

hugo-doc 专注于个人品牌展示，配置简洁：

 1# user-configuration/themes/hugo-doc/params.toml
 2
 3[hugoDoc]
 4  brandIcon = '🪁'                    # ◀️ 品牌图标（Emoji）
 5  brandName = '纸鸢博客'               # ◀️ 品牌名称
 6  heroGreeting = '你好，我是'           # ◀️ Hero 问候语
 7  heroRole = '全栈开发者 / 设计爱好者'  # ◀️ 角色描述
 8  heroDescription = '热爱技术与设计...'  # ◀️ 个人简介
 9  heroPrimaryText = '查看作品'          # ◀️ 主按钮文本
10  heroPrimaryURL = '/#projects'        # ◀️ 主按钮链接
11
12[search]
13  enabled = false             # ◀️ 搜索功能默认关闭
1# user-configuration/themes/hugo-doc/params.toml
2
3[hugoDoc]
4  skillsEnabled = true        # ◀️ 启用技能展示区域
5  projectsEnabled = true      # ◀️ 启用项目作品区域
6  docsLimit = 6               # ◀️ 最新文章展示数量
7  docsTitle = '最新文章'       # ◀️ 文档区域标题
8  docsSubtitle = '分享技术...' # ◀️ 文档区域副标题

hugo-simple 主题配置

hugo-simple 追求极简，配置项最少：

 1# user-configuration/themes/hugo-simple/params.toml
 2
 3[params]
 4  heroTitle = 'wiki.xxdevops.cn | 余温Gueen'   # ◀️ 首页标题
 5  heroSubtitle = '纵然世间晦暗，仍有一点星光。'   # ◀️ 首页副标题
 6  heroImage = '/images/banner/slide6.jpg'        # ◀️ 首页图片
 7  author = 'admin'                               # ◀️ 作者名称
 8  avatarImage = 'https://xxx/avatar.avif'        # ◀️ 头像地址
 9  avatarLink = '/about/'                         # ◀️ 头像链接
10  description = '余温Gueen - 技术博客'            # ◀️ 站点描述
11
12[params.search]
13  enabled = false              # ◀️ 搜索功能默认关闭
1# hugo-simple 支持多种配色方案
2# 配置文件位于 themes/hugo-simple/assets/css/color-schemes/
3#
4# 可用方案：
5# - default  （默认）
6# - pure     （纯净）
7# - warm     （暖色调）
8# - eye      （护眼）
9# - cool     （冷色调）

🔄 配置合并机制

合并流程

Hugo-Teek 使用 hugo-teek-tools config merge 工具自动合并配置文件：

1📋 配置合并顺序（优先级从低到高）：
2
31️⃣ user-configuration/themes/{主题名}/*.toml    → 主题默认配置
42️⃣ user-configuration/teek-plugins/*.toml        → 通用插件配置
53️⃣ user-configuration/hugo.toml                  → 站点基础配置
6                                    ↓
7            hugo-teek-site/config/_default/*.toml  → 合并输出（自动生成）

⚠️ 重要提示

hugo-teek-site/config/_default/ 目录下的文件是自动生成的，请勿手动编辑。每次运行 make dev 或 make build 时，构建工具会自动重新合并配置。

合并后的输出文件

输出文件内容来源说明
config/_default/hugo.tomluser-configuration/hugo.toml站点基础配置
config/_default/params.tomlteek-plugins/*.toml + themes/{主题}/params.toml合并后的参数配置
config/_default/menus.tomlteek-plugins/menus.toml + themes/{主题}/menus.toml菜单配置
config/_default/module.tomlteek-plugins/ + themes/{主题}/module.tomlHugo Modules 配置
config/_default/sections.tomlteek-plugins/sections.toml分区配置

🧪 主题切换示例

示例一：从 hugo-teek 切换到 hugo-doc

1# user-configuration/hugo.toml
2theme = 'hugo-teek'
1# user-configuration/hugo.toml
2theme = 'hugo-doc'
1# 重启开发服务器使配置生效
2make dev
3
4# 或临时指定主题
5make dev THEME=hugo-doc

示例二：自定义 hugo-doc 主题配置

 1# user-configuration/themes/hugo-doc/params.toml
 2
 3[hugoDoc]
 4  brandIcon = '🚀'                          # ◀️ 修改品牌图标
 5  brandName = '我的技术博客'                  # ◀️ 修改品牌名称
 6  heroGreeting = 'Hi there!'                # ◀️ 修改问候语
 7  heroRole = 'Backend Developer'            # ◀️ 修改角色
 8  heroDescription = '专注于 Go 和云原生技术'  # ◀️ 修改简介
 9  heroPrimaryText = '查看项目'               # ◀️ 主按钮文本
10  heroPrimaryURL = '/#projects'             # ◀️ 主按钮链接
11  heroSecondaryText = '关于我'              # ◀️ 副按钮文本
12  heroSecondaryURL = '/about/'              # ◀️ 副按钮链接
13  skillsEnabled = true                      # ◀️ 显示技能区域
14  projectsEnabled = true                    # ◀️ 显示项目区域
15  docsLimit = 8                             # ◀️ 展示 8 篇最新文章
16
17[search]
18  enabled = false                           # ◀️ 关闭搜索
1# 启动开发服务器预览效果
2make dev THEME=hugo-doc
3
4# 构建生产版本
5make build THEME=hugo-doc

🔧 常见问题

主题切换后样式异常

1原因：主题专属配置文件缺失或格式错误
2解决：
31️⃣ 检查 user-configuration/themes/{主题名}/ 目录是否存在
42️⃣ 检查 params.toml 文件格式是否正确（TOML 语法）
53️⃣ 运行 make clean 清理缓存后重新启动
64️⃣ 查看终端输出是否有配置合并错误信息
1原因：新主题默认关闭了搜索功能
2解决：
31️⃣ 检查 user-configuration/themes/{主题名}/params.toml
42️⃣ 确认 [search] enabled = true
53️⃣ 重新启动开发服务器（make dev）
64️⃣ 注意：hugo-doc 和 hugo-simple 默认关闭搜索
1原因：THEME 参数与配置文件中的 theme 字段冲突
2解决：
31️⃣ THEME 参数会覆盖配置文件中的 theme 字段
42️⃣ 确认主题名称拼写正确（区分大小写）
53️⃣ 确认 themes/ 目录下存在对应主题文件夹
64️⃣ 运行 make clean 清理后重试

配置合并失败

1原因：TOML 文件格式错误或存在重复键
2解决：
31️⃣ 检查所有 .toml 文件的语法格式
42️⃣ 确认没有重复的配置键名
53️⃣ 使用在线 TOML 校验工具检查语法
64️⃣ 查看终端错误信息定位具体文件和行号
1原因：配置优先级理解错误
2解决：
31️⃣ 确认配置文件放在正确的目录下
42️⃣ 主题专属配置 < 通用插件配置（通用配置会覆盖主题配置）
53️⃣ 如需主题配置优先，不要在通用配置中设置相同字段
64️⃣ 检查 config/_default/params.toml 确认合并结果

主题切换检查清单

1📋 主题切换前检查清单：
2
3✅ themes/ 目录下存在目标主题文件夹
4✅ user-configuration/themes/{主题名}/ 目录存在
5✅ 目标主题的 params.toml 格式正确
6✅ hugo.toml 中 theme 字段拼写正确
7✅ 已运行 make clean 清理旧缓存
8✅ 重新启动开发服务器（make dev）
9✅ 浏览器访问 http://localhost:8090 预览效果

📋 快速切换速查表

主题配置模板

 1# user-configuration/hugo.toml
 2theme = 'hugo-teek'
 3
 4# user-configuration/themes/hugo-teek/params.toml
 5layoutMode = 'bothWidthAdjustable'
 6
 7[blogger]
 8  name = '你的名字'
 9  slogan = '你的签名'
10  avatar = 'https://xxx/avatar.avif'
11  shape = 'circle-rotate'
12
13[search]
14  enabled = true
 1# user-configuration/hugo.toml
 2theme = 'hugo-doc'
 3
 4# user-configuration/themes/hugo-doc/params.toml
 5[hugoDoc]
 6  brandIcon = '🪁'
 7  brandName = '我的博客'
 8  heroGreeting = '你好，我是'
 9  heroRole = '开发者'
10  heroDescription = '个人简介'
11  skillsEnabled = true
12  projectsEnabled = true
13
14[search]
15  enabled = false
 1# user-configuration/hugo.toml
 2theme = 'hugo-simple'
 3
 4# user-configuration/themes/hugo-simple/params.toml
 5[params]
 6  heroTitle = '我的博客'
 7  heroSubtitle = '博客副标题'
 8  author = '作者名'
 9  avatarImage = 'https://xxx/avatar.avif'
10  description = '博客描述'
11
12[params.search]
13  enabled = false

常用命令速查

命令说明
make dev启动开发服务器（自动检测主题）
make dev THEME=主题名临时指定主题启动
make build构建生产版本（自动检测主题）
make build THEME=主题名临时指定主题构建
make clean清理构建缓存
make quick快速启动（跳过数据生成）

🔗 相关资源

📚 推荐阅读

🎉 主题切换配置完成！

如有问题，请在 Hugo-Teek 项目仓库 的 Issues 中反馈

📡
👤 作者: 余温Gueen
🔗 链接: https://example.com/hobby/ciiuq
🌐 版权: 本站文章除特别声明外，均采用 CC BY-NC-SA 4.0 协议，转载请注明来自 余温Gueen Blog！
推荐使用微信支付
微信支付二维码
推荐使用支付宝
支付宝二维码
最新文章