2026-03-02 博客 hugo-teek +3 导航栏配置菜单设置配置说明 1836 字 8 分钟 -- 次

导航栏配置说明

最后更新于: 2026-03-02 04:47:45

🧭 导航栏配置概述

Hugo-Teek 主题采用灵活的菜单配置系统，支持多级下拉菜单、图标配置、外部链接等多种功能。导航栏配置采用 TOML 格式，通过 Hugo 原生的菜单系统进行管理。

✨ 导航栏特性

🎨 设计特性

多级下拉菜单：支持无限层级嵌套
图标支持：内置 Bootstrap Icons 图标库
外部链接：支持新窗口打开外部链接
响应式布局：移动端自动折叠为汉堡菜单

⚙️ 配置特性

权重排序：通过 weight 控制菜单顺序
标识符系统：使用 identifier 建立层级关系
参数扩展：支持自定义参数扩展功能
主题隔离：不同主题可拥有独立菜单配置

📁 配置文件路径

Hugo-Teek 采用分层配置结构，菜单配置文件位于以下位置：

通用菜单配置📄 主题特定菜单📄

1# hugo-teek-site/config/teek-plugins/menus.toml
2# 所有主题共用的菜单配置
3# 推荐在此文件中进行菜单配置

1# hugo-teek-site/config/themes/hugo-teek/menus.toml
2# 仅当前主题使用的菜单配置
3# 用于覆盖通用配置

配置优先级

1配置合并顺序（优先级从低到高）：
21️⃣ config/themes/{theme}/menus.toml（主题默认配置）
32️⃣ config/teek-plugins/menus.toml（通用配置）
43️⃣ 运行时通过管理后台修改的配置

📝 基础菜单配置

单级菜单项

最简单的菜单配置，只包含名称、链接和排序权重：

基础菜单项📝 配置说明📝

1[[main]]
2  name = "🏡 首页"
3  url = "/"
4  weight = 1

1[[main]]              # ◀️ 菜单组标识，固定为 main
2  name = "🏡 首页"     # ◀️ 显示名称，支持 emoji
3  url = "/"           # ◀️ 链接地址，支持相对/绝对路径
4  weight = 1          # ◀️ 排序权重，数字越小越靠前

菜单配置字段说明

字段	必填	说明
`name`	✅	菜单显示名称，支持 emoji 图标
`url`	✅	链接地址，相对路径或绝对 URL
`weight`	✅	排序权重，数字越小越靠前
`identifier`	❌	唯一标识符，用于建立父子关系
`parent`	❌	父菜单的 identifier，用于创建子菜单

🌳 多级下拉菜单

创建下拉菜单结构

通过 identifier 和 parent 字段建立层级关系：

完整多级菜单🌳 层级关系说明📝

 1# 一级菜单（父菜单）
 2[[main]]
 3  identifier = "tech"      # ◀️ 唯一标识符
 4  name = "📚 技术分类"
 5  url = "#"                # ◀️ # 表示纯下拉，不跳转
 6  weight = 2
 7
 8# 二级菜单（子菜单）
 9[[main]]
10  name = "🖥️ 运维"
11  parent = "tech"          # ◀️ 对应父菜单的 identifier
12  url = "/linux/"
13  weight = 1
14
15[[main]]
16  name = "🎨 前端"
17  parent = "tech"
18  url = "/frontend/"
19  weight = 2

1📚 技术分类 (identifier: tech)
2├── 🖥️ 运维 (parent: tech)
3├── 🎨 前端 (parent: tech)
4└── 💻 编程 (parent: tech)

多级菜单最佳实践

⚠️ 注意事项

父菜单的 identifier 必须唯一，不可重复
子菜单的 parent 值必须与父菜单的 identifier 完全匹配
父菜单设置 url = "#" 表示纯下拉菜单，点击不跳转
建议合理设置 weight，保持菜单逻辑顺序

🎨 图标配置

使用 Bootstrap Icons

Hugo-Teek 内置 Bootstrap Icons 图标库，可通过 params.icon 配置菜单图标：

带图标的菜单🎨 常用图标示例🎨

1[[main]]
2  name = "🖥️ 运维"
3  parent = "tech"
4  url = "/linux/"
5  weight = 1
6  [main.params]
7    icon = "monitor"     # ◀️ Bootstrap Icons 名称

1  icon = "house"        # ◀️ 首页图标
2  icon = "book"         # ◀️ 文档图标
3  icon = "code"         # ◀️ 代码图标
4  icon = "github"       # ◀️ GitHub 图标
5  icon = "link"         # ◀️ 链接图标
6  icon = "folder"       # ◀️ 文件夹图标

图标查找与使用

🔍 图标资源

图标库：Bootstrap Icons
使用方式：复制图标名称（不含 bi- 前缀）
示例：bi-house → 配置为 icon = "house"

🔗 外部链接配置

配置外部链接菜单

通过 params.external 和 params.target 配置外部链接：

外部链接🔗 外部链接参数说明📝

1[[main]]
2  name = "⏱️ 时间轴"
3  parent = "about"
4  url = "https://wiki.xxdevops.cn/"
5  weight = 32
6  [main.params]
7    icon = "clock"
8    external = true      # ◀️ 标记为外部链接
9    target = "_blank"    # ◀️ 在新窗口打开

1  external = true       # ◀️ 添加外部链接标识（可选）
2  target = "_blank"     # ◀️ 新窗口打开：_blank
3                        # ◀️ 当前窗口打开：_self（默认）

外部链接与内部链接对比

内部链接🏠 外部链接🌐

1[[main]]
2  name = "👋 关于我"
3  url = "/about/"
4  weight = 1
5  # ◀️ 无需 external 和 target 参数

1[[main]]
2  name = "📊 网站统计"
3  url = "https://umami.xxdevops.cn/"
4  weight = 2
5  [main.params]
6    external = true
7    target = "_blank"

📋 完整配置示例

典型博客导航栏配置

完整配置示例📋

  1# ========================================
  2# 🏠 首页
  3# ========================================
  4[[main]]
  5  name = "🏡 首页"
  6  url = "/"
  7  weight = 1
  8
  9# ========================================
 10# 📚 技术分类（下拉菜单）
 11# ========================================
 12[[main]]
 13  identifier = "tech"
 14  name = "📚 技术分类"
 15  url = "#"
 16  weight = 2
 17
 18[[main]]
 19  name = "🖥️ 运维"
 20  parent = "tech"
 21  url = "/linux/"
 22  weight = 1
 23  [main.params]
 24    icon = "monitor"
 25
 26[[main]]
 27  name = "🎨 前端"
 28  parent = "tech"
 29  url = "/frontend/"
 30  weight = 2
 31  [main.params]
 32    icon = "code"
 33
 34# ========================================
 35# 📝 专题（下拉菜单）
 36# ========================================
 37[[main]]
 38  identifier = "topics"
 39  name = "🛠️ 专题"
 40  url = "#"
 41  weight = 3
 42
 43[[main]]
 44  name = "📝 博客搭建"
 45  parent = "topics"
 46  url = "/topic/"
 47  weight = 1
 48  [main.params]
 49    icon = "book"
 50
 51# ========================================
 52# 👏 索引（下拉菜单）
 53# ========================================
 54[[main]]
 55  identifier = "index"
 56  name = "👏 索引"
 57  url = "#"
 58  weight = 4
 59
 60[[main]]
 61  name = "🔖 标签页"
 62  parent = "index"
 63  url = "/tags/"
 64  weight = 1
 65  [main.params]
 66    icon = "tag"
 67
 68[[main]]
 69  name = "📃 分类页"
 70  parent = "index"
 71  url = "/categories/"
 72  weight = 2
 73  [main.params]
 74    icon = "folder"
 75
 76[[main]]
 77  name = "📚 归档页"
 78  parent = "index"
 79  url = "/archives/"
 80  weight = 3
 81  [main.params]
 82    icon = "archive"
 83
 84# ========================================
 85# 🍷 关于（下拉菜单）
 86# ========================================
 87[[main]]
 88  identifier = "about"
 89  name = "🍷 关于"
 90  url = "#"
 91  weight = 5
 92
 93[[main]]
 94  name = "👋 关于我"
 95  parent = "about"
 96  url = "/about/"
 97  weight = 1
 98  [main.params]
 99    icon = "user"
100
101[[main]]
102  name = "💖 友链"
103  parent = "about"
104  url = "/about/friend-links/"
105  weight = 2
106  [main.params]
107    icon = "link"
108
109[[main]]
110  name = "⏱️ 时间轴"
111  parent = "about"
112  url = "https://wiki.xxdevops.cn/"
113  weight = 3
114  [main.params]
115    icon = "clock"
116    external = true
117    target = "_blank"

⚙️ 通过管理后台配置

使用 Hugo Teek Admin

Hugo-Teek 提供可视化管理后台，可图形化配置导航栏：

启动管理后台🚀 后台配置路径📝

1make dev-admin
2# 访问: http://localhost:8080

11️⃣ 登录管理后台
22️⃣ 进入「外观管理」->「菜单」
33️⃣ 可视化添加/编辑/删除菜单项
44️⃣ 拖拽调整菜单顺序
55️⃣ 保存后自动生成配置

配置方式对比

配置方式	适用场景	难度	灵活性
管理后台	快速调整、可视化编辑	⭐ 简单	⭐⭐⭐
手动编辑	批量修改、版本控制	⭐⭐ 中等	⭐⭐⭐⭐⭐
主题配置	主题开发、默认菜单	⭐⭐⭐ 复杂	⭐⭐⭐⭐

🔧 常见问题

菜单不显示或显示异常

问题1：菜单不显示❌ 问题2：排序混乱❌ 问题3：图标不显示❌

1原因：identifier 重复或 parent 不匹配
2解决：
31️⃣ 检查所有 identifier 是否唯一
42️⃣ 检查 parent 值是否与父菜单 identifier 一致
53️⃣ 重启开发服务器：make dev

1原因：weight 值设置不当
2解决：
31️⃣ 同级菜单使用连续的 weight 值
42️⃣ 建议以 10 为间隔，方便后续插入
53️⃣ 父菜单 weight 应小于子菜单

1原因：icon 名称错误或格式问题
2解决：
31️⃣ 访问 Bootstrap Icons 官网确认图标名称
42️⃣ 去掉 bi- 前缀，如 bi-house → house
53️⃣ 检查 params 缩进是否正确

配置生效检查清单

1✅ 配置文件路径正确
2✅ TOML 语法无误（使用在线 TOML 验证器检查）
3✅ identifier 唯一不重复
4✅ parent 与 identifier 匹配
5✅ weight 数值合理
6✅ 重启开发服务器后生效

📝 配置模板速查

常用菜单模板

单级菜单模板📝 下拉菜单父级模板📝 下拉菜单子级模板📝 外部链接模板📝

1[[main]]
2  name = "菜单名称"
3  url = "/path/"
4  weight = 10

1[[main]]
2  identifier = "unique-id"
3  name = "下拉菜单"
4  url = "#"
5  weight = 10

1[[main]]
2  name = "子菜单项"
3  parent = "unique-id"
4  url = "/path/"
5  weight = 1
6  [main.params]
7    icon = "icon-name"

1[[main]]
2  name = "外部链接"
3  url = "https://example.com"
4  weight = 10
5  [main.params]
6    icon = "link"
7    external = true
8    target = "_blank"

🎉 导航栏配置完成！

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

📡

👤 作者: 余温Gueen

🔗 链接: https://wiki.xxdevops.cn/hobby/daohanglan-peizhi

🌐 版权: 本站文章除特别声明外，均采用 CC BY-NC-SA 4.0 协议，转载请注明来自余温Gueen Blog！

推荐使用微信支付

推荐使用支付宝

上一篇博主卡片配置说明下一篇 Hugo-Teek博客介绍