头像 余温Gueen
头像
余温Gueen
-- : -- : --
切换主题色
-- : -- : --
博客 hugo-teek +4 目录样式侧边栏样式CSS变量进阶配置 3158 字 15 分钟 -- 次

修改目录样式

最后更新于:

📑 目录样式修改概述

Hugo-Teek 主题支持通过 CSS 变量自定义文档落地页左侧目录的样式，包括文本颜色、背景色、悬停效果等。通过统一的 CSS 变量系统，可以轻松实现亮色/暗色模式下的样式适配。

✨ 可自定义的样式项

🎨 样式定制范围

  • 文本颜色：普通文本、选中文本、悬停文本
  • 背景颜色：容器背景、选中背景、悬停背景
  • 子目录样式：下拉后的文本色、悬停样式、选中样式
  • 边框与阴影：分隔线、圆角、阴影效果

⚙️ 技术特性

  • CSS 变量管理：使用 CSS 自定义属性实现样式统一管理
  • 主题适配：支持亮色/暗色模式自动切换
  • 层级样式：父目录与子目录样式独立配置
  • 响应式：移动端样式自动适配

📁 样式文件路径

目录样式配置文件位于以下位置：

1/* hugo-teek-site/assets/css/custom/sidebar.scss */
2/* 所有主题共用的目录样式配置 */
3/* 推荐在此文件中进行样式配置 */
1/* hugo-teek-site/assets/themes/hugo-teek/css/sidebar.scss */
2/* 仅当前主题使用的目录样式配置 */
3/* 用于覆盖通用配置 */
1/* hugo-teek-site/assets/css/variables.scss */
2/* 全局 CSS 变量定义文件 */
3/* 定义目录样式的基础变量 */

配置优先级

1样式合并顺序（优先级从低到高）：
21️⃣ assets/css/variables.scss（基础变量定义）
32️⃣ assets/themes/{theme}/css/sidebar.scss（主题默认样式）
43️⃣ assets/css/custom/sidebar.scss（用户自定义样式）

🎨 CSS 变量说明

基础变量定义

首先需要在变量文件中定义目录样式的基础 CSS 变量：

 1/* hugo-teek-site/assets/css/variables.scss */
 2
 3/* ================================
 4   📑 目录样式变量
 5   ================================ */
 6
 7/* ☀️ 亮色模式变量 */
 8:root {
 9  /* 容器背景 */
10  --sidebar-bg: #ffffff;                    /* ◀️ 侧边栏容器背景色 */
11  --sidebar-border-color: #e5e7eb;          /* ◀️ 侧边栏边框颜色 */
12  
13  /* 文本颜色 */
14  --sidebar-text-color: #374151;            /* ◀️ 普通文本颜色 */
15  --sidebar-text-hover: #111827;            /* ◀️ 悬停文本颜色 */
16  --sidebar-text-active: #2563eb;           /* ◀️ 选中文本颜色 */
17  
18  /* 背景颜色 */
19  --sidebar-item-hover-bg: #f3f4f6;         /* ◀️ 悬停背景色 */
20  --sidebar-item-active-bg: #eff6ff;        /* ◀️ 选中背景色 */
21  
22  /* 子目录样式 */
23  --sidebar-child-text-color: #4b5563;      /* ◀️ 子目录文本颜色 */
24  --sidebar-child-text-hover: #1f2937;      /* ◀️ 子目录悬停文本色 */
25  --sidebar-child-text-active: #2563eb;     /* ◀️ 子目录选中文本色 */
26  --sidebar-child-bg: #f9fafb;              /* ◀️ 子目录背景色 */
27}
28
29/* 🌆 暗色模式变量 */
30[data-theme="dark"] {
31  /* 容器背景 */
32  --sidebar-bg: #1f2937;                    /* ◀️ 侧边栏容器背景色 */
33  --sidebar-border-color: #374151;          /* ◀️ 侧边栏边框颜色 */
34  
35  /* 文本颜色 */
36  --sidebar-text-color: #d1d5db;            /* ◀️ 普通文本颜色 */
37  --sidebar-text-hover: #f9fafb;            /* ◀️ 悬停文本颜色 */
38  --sidebar-text-active: #60a5fa;           /* ◀️ 选中文本颜色 */
39  
40  /* 背景颜色 */
41  --sidebar-item-hover-bg: #374151;         /* ◀️ 悬停背景色 */
42  --sidebar-item-active-bg: #1e3a8a;        /* ◀️ 选中背景色 */
43  
44  /* 子目录样式 */
45  --sidebar-child-text-color: #9ca3af;      /* ◀️ 子目录文本颜色 */
46  --sidebar-child-text-hover: #e5e7eb;      /* ◀️ 子目录悬停文本色 */
47  --sidebar-child-text-active: #60a5fa;     /* ◀️ 子目录选中文本色 */
48  --sidebar-child-bg: #111827;              /* ◀️ 子目录背景色 */
49}
1/* 变量命名规范：
2 * --sidebar-{元素}-{状态}-{属性}
3 * 
4 * 元素：bg(背景)、text(文本)、item(菜单项)、child(子目录)
5 * 状态：hover(悬停)、active(选中)、无(默认状态)
6 * 属性：color(颜色)、bg(背景色)
7 */

变量使用示例

 1/* 在样式文件中使用变量 */
 2.simple-sidebar {
 3  background-color: var(--sidebar-bg);
 4  border-right: 1px solid var(--sidebar-border-color);
 5}
 6
 7.simple-sidebar__link {
 8  color: var(--sidebar-text-color);
 9}
10
11.simple-sidebar__link:hover {
12  color: var(--sidebar-text-hover);
13  background-color: var(--sidebar-item-hover-bg);
14}
15
16.simple-sidebar__item.is-active .simple-sidebar__link {
17  color: var(--sidebar-text-active);
18  background-color: var(--sidebar-item-active-bg);
19}
1/* 使用 fallback 值确保兼容性 */
2.simple-sidebar {
3  background-color: var(--sidebar-bg, #ffffff);
4}
5
6/* 嵌套使用变量 */
7.simple-sidebar__children {
8  background-color: var(--sidebar-child-bg, var(--sidebar-bg));
9}

📝 目录样式配置

容器样式配置

配置侧边栏容器的背景色、边框等基础样式：

 1/* hugo-teek-site/assets/css/custom/sidebar.scss */
 2
 3/* ================================
 4   📦 侧边栏容器样式
 5   ================================ */
 6
 7.simple-sidebar {
 8  /* 基础布局 */
 9  display: flex;
10  flex-direction: column;
11  width: 280px;                             /* ◀️ 侧边栏宽度 */
12  height: 100vh;                            /* ◀️ 占满视口高度 */
13  
14  /* 背景与边框 */
15  background-color: var(--sidebar-bg);      /* ◀️ 使用变量定义背景色 */
16  border-right: 1px solid var(--sidebar-border-color);
17  
18  /* 滚动行为 */
19  overflow-y: auto;
20  scrollbar-width: thin;
21  scrollbar-color: var(--sidebar-border-color) transparent;
22}
23
24/* 滚动条样式 */
25.simple-sidebar::-webkit-scrollbar {
26  width: 6px;
27}
28
29.simple-sidebar::-webkit-scrollbar-thumb {
30  background-color: var(--sidebar-border-color);
31  border-radius: 3px;
32}
 1/* 添加阴影效果 */
 2.simple-sidebar {
 3  box-shadow: 2px 0 8px rgba(0, 0, 0, 0.05);
 4}
 5
 6/* 🌆 暗色模式阴影 */
 7[data-theme="dark"] .simple-sidebar {
 8  box-shadow: 2px 0 8px rgba(0, 0, 0, 0.2);
 9}
10
11/* 圆角配置 */
12.simple-sidebar {
13  border-radius: 0 12px 12px 0;             /* ◀️ 右侧圆角 */
14}

菜单项文本样式

配置目录菜单项的文本颜色、悬停效果和选中状态：

 1/* ================================
 2   📝 菜单项文本样式
 3   ================================ */
 4
 5.simple-sidebar__link {
 6  /* 基础文本样式 */
 7  color: var(--sidebar-text-color);         /* ◀️ 普通文本颜色 */
 8  font-size: 14px;                          /* ◀️ 字体大小 */
 9  font-weight: 400;                         /* ◀️ 字体粗细 */
10  line-height: 1.5;
11  text-decoration: none;
12  
13  /* 过渡动画 */
14  transition: color 0.2s ease, background-color 0.2s ease;
15}
16
17/* 悬停状态 */
18.simple-sidebar__link:hover {
19  color: var(--sidebar-text-hover);         /* ◀️ 悬停文本颜色 */
20}
21
22/* 选中状态 */
23.simple-sidebar__item.is-active .simple-sidebar__link {
24  color: var(--sidebar-text-active);        /* ◀️ 选中文本颜色 */
25  font-weight: 500;                         /* ◀️ 选中时加粗 */
26}
 1/* ☀️ 亮色模式文本色值参考 */
 2:root {
 3  --sidebar-text-color: #374151;            /* ◀️ 灰色-700 */
 4  --sidebar-text-hover: #111827;            /* ◀️ 灰色-900 */
 5  --sidebar-text-active: #2563eb;           /* ◀️ 蓝色-600 */
 6}
 7
 8/* 🌆 暗色模式文本色值参考 */
 9[data-theme="dark"] {
10  --sidebar-text-color: #d1d5db;            /* ◀️ 灰色-300 */
11  --sidebar-text-hover: #f9fafb;            /* ◀️ 灰色-50 */
12  --sidebar-text-active: #60a5fa;           /* ◀️ 蓝色-400 */
13}

背景色配置

配置菜单项的悬停背景色和选中背景色：

 1/* ================================
 2   🎨 菜单项背景样式
 3   ================================ */
 4
 5.simple-sidebar__item-inner {
 6  /* 基础样式 */
 7  padding: 8px 16px;
 8  border-radius: 6px;                       /* ◀️ 圆角 */
 9  margin: 2px 8px;
10  
11  /* 过渡动画 */
12  transition: background-color 0.2s ease;
13}
14
15/* 悬停背景 */
16.simple-sidebar__item:hover .simple-sidebar__item-inner,
17.simple-sidebar__item-inner:hover {
18  background-color: var(--sidebar-item-hover-bg);
19}
20
21/* 选中背景 */
22.simple-sidebar__item.is-active .simple-sidebar__item-inner {
23  background-color: var(--sidebar-item-active-bg);
24}
25
26/* 选中+悬停组合状态 */
27.simple-sidebar__item.is-active:hover .simple-sidebar__item-inner {
28  background-color: var(--sidebar-item-active-bg);
29  opacity: 0.9;
30}
 1/* ☀️ 亮色模式背景色 */
 2:root {
 3  --sidebar-item-hover-bg: #f3f4f6;         /* ◀️ 灰色-100 */
 4  --sidebar-item-active-bg: #eff6ff;        /* ◀️ 蓝色-50 */
 5}
 6
 7/* 🌆 暗色模式背景色 */
 8[data-theme="dark"] {
 9  --sidebar-item-hover-bg: #374151;         /* ◀️ 灰色-700 */
10  --sidebar-item-active-bg: #1e3a8a;        /* ◀️ 蓝色-900 */
11}

🌳 子目录样式配置

子目录容器样式

配置子目录下拉后的容器样式：

 1/* ================================
 2   🌳 子目录容器样式
 3   ================================ */
 4
 5.simple-sidebar__children {
 6  /* 基础布局 */
 7  margin-left: 16px;                        /* ◀️ 左侧缩进 */
 8  padding-left: 12px;
 9  
10  /* 背景与边框 */
11  background-color: var(--sidebar-child-bg);
12  border-left: 2px solid var(--sidebar-border-color);
13  
14  /* 动画效果 */
15  transition: max-height 0.3s ease, opacity 0.3s ease;
16}
17
18/* 展开状态 */
19.simple-sidebar__item.has-children.is-expanded .simple-sidebar__children {
20  display: block;
21  opacity: 1;
22}
23
24/* 收起状态 */
25.simple-sidebar__item.has-children:not(.is-expanded) .simple-sidebar__children {
26  display: none;
27  opacity: 0;
28}
 1/* 添加圆角和阴影 */
 2.simple-sidebar__children {
 3  border-radius: 0 8px 8px 0;
 4  margin-right: 8px;
 5}
 6
 7/* 子目录项间距 */
 8.simple-sidebar__children .simple-sidebar__item {
 9  margin: 2px 0;
10}

子目录文本样式

配置子目录下拉后的文本颜色、悬停样式和选中样式：

 1/* ================================
 2   📝 子目录文本样式
 3   ================================ */
 4
 5.simple-sidebar__children .simple-sidebar__link {
 6  /* 子目录文本颜色 */
 7  color: var(--sidebar-child-text-color);
 8  font-size: 13px;                          /* ◀️ 子目录字体稍小 */
 9}
10
11/* 子目录悬停样式 */
12.simple-sidebar__children .simple-sidebar__link:hover {
13  color: var(--sidebar-child-text-hover);
14}
15
16/* 子目录选中样式 */
17.simple-sidebar__children .simple-sidebar__item.is-active .simple-sidebar__link {
18  color: var(--sidebar-child-text-active);
19}
 1/* ☀️ 亮色模式子目录样式 */
 2:root {
 3  --sidebar-child-text-color: #4b5563;      /* ◀️ 灰色-600 */
 4  --sidebar-child-text-hover: #1f2937;      /* ◀️ 灰色-800 */
 5  --sidebar-child-text-active: #2563eb;     /* ◀️ 蓝色-600 */
 6  --sidebar-child-bg: #f9fafb;              /* ◀️ 灰色-50 */
 7}
 8
 9/* 🌆 暗色模式子目录样式 */
10[data-theme="dark"] {
11  --sidebar-child-text-color: #9ca3af;      /* ◀️ 灰色-400 */
12  --sidebar-child-text-hover: #e5e7eb;      /* ◀️ 灰色-200 */
13  --sidebar-child-text-active: #60a5fa;     /* ◀️ 蓝色-400 */
14  --sidebar-child-bg: #111827;              /* ◀️ 灰色-900 */
15}

📋 完整配置示例

完整变量定义

 1/* hugo-teek-site/assets/css/variables.scss */
 2
 3/* ================================
 4   📑 目录样式完整变量
 5   ================================ */
 6
 7/* ☀️ 亮色模式 */
 8:root {
 9  /* 容器 */
10  --sidebar-bg: #ffffff;
11  --sidebar-border-color: #e5e7eb;
12  
13  /* 父目录文本 */
14  --sidebar-text-color: #374151;
15  --sidebar-text-hover: #111827;
16  --sidebar-text-active: #2563eb;
17  
18  /* 父目录背景 */
19  --sidebar-item-hover-bg: #f3f4f6;
20  --sidebar-item-active-bg: #eff6ff;
21  
22  /* 子目录文本 */
23  --sidebar-child-text-color: #4b5563;
24  --sidebar-child-text-hover: #1f2937;
25  --sidebar-child-text-active: #2563eb;
26  
27  /* 子目录背景 */
28  --sidebar-child-bg: #f9fafb;
29  
30  /* 其他 */
31  --sidebar-transition: 0.2s ease;
32}
33
34/* 🌆 暗色模式 */
35[data-theme="dark"] {
36  /* 容器 */
37  --sidebar-bg: #1f2937;
38  --sidebar-border-color: #374151;
39  
40  /* 父目录文本 */
41  --sidebar-text-color: #d1d5db;
42  --sidebar-text-hover: #f9fafb;
43  --sidebar-text-active: #60a5fa;
44  
45  /* 父目录背景 */
46  --sidebar-item-hover-bg: #374151;
47  --sidebar-item-active-bg: #1e3a8a;
48  
49  /* 子目录文本 */
50  --sidebar-child-text-color: #9ca3af;
51  --sidebar-child-text-hover: #e5e7eb;
52  --sidebar-child-text-active: #60a5fa;
53  
54  /* 子目录背景 */
55  --sidebar-child-bg: #111827;
56}
 1/* hugo-teek-site/assets/css/custom/sidebar.scss */
 2
 3/* ================================
 4   📑 目录样式完整配置
 5   ================================ */
 6
 7/* 容器 */
 8.simple-sidebar {
 9  background-color: var(--sidebar-bg);
10  border-right: 1px solid var(--sidebar-border-color);
11}
12
13/* 菜单项 */
14.simple-sidebar__item-inner {
15  padding: 8px 16px;
16  margin: 2px 8px;
17  border-radius: 6px;
18  transition: background-color var(--sidebar-transition);
19}
20
21/* 文本 */
22.simple-sidebar__link {
23  color: var(--sidebar-text-color);
24  font-size: 14px;
25  transition: color var(--sidebar-transition);
26}
27
28.simple-sidebar__link:hover {
29  color: var(--sidebar-text-hover);
30}
31
32/* 悬停背景 */
33.simple-sidebar__item:hover .simple-sidebar__item-inner {
34  background-color: var(--sidebar-item-hover-bg);
35}
36
37/* 选中状态 */
38.simple-sidebar__item.is-active .simple-sidebar__link {
39  color: var(--sidebar-text-active);
40  font-weight: 500;
41}
42
43.simple-sidebar__item.is-active .simple-sidebar__item-inner {
44  background-color: var(--sidebar-item-active-bg);
45}
46
47/* 子目录 */
48.simple-sidebar__children {
49  margin-left: 16px;
50  padding-left: 12px;
51  background-color: var(--sidebar-child-bg);
52  border-left: 2px solid var(--sidebar-border-color);
53}
54
55.simple-sidebar__children .simple-sidebar__link {
56  color: var(--sidebar-child-text-color);
57  font-size: 13px;
58}
59
60.simple-sidebar__children .simple-sidebar__link:hover {
61  color: var(--sidebar-child-text-hover);
62}
63
64.simple-sidebar__children .simple-sidebar__item.is-active .simple-sidebar__link {
65  color: var(--sidebar-child-text-active);
66}

🎯 主题配色方案

蓝色主题

 1/* 经典蓝色主题 */
 2:root {
 3  --sidebar-text-active: #2563eb;
 4  --sidebar-item-active-bg: #eff6ff;
 5  --sidebar-child-text-active: #2563eb;
 6}
 7
 8[data-theme="dark"] {
 9  --sidebar-text-active: #60a5fa;
10  --sidebar-item-active-bg: #1e3a8a;
11  --sidebar-child-text-active: #60a5fa;
12}
 1/* 深蓝色主题 */
 2:root {
 3  --sidebar-text-active: #1d4ed8;
 4  --sidebar-item-active-bg: #dbeafe;
 5  --sidebar-child-text-active: #1d4ed8;
 6}
 7
 8[data-theme="dark"] {
 9  --sidebar-text-active: #3b82f6;
10  --sidebar-item-active-bg: #172554;
11  --sidebar-child-text-active: #3b82f6;
12}

绿色主题

 1/* 清新绿色主题 */
 2:root {
 3  --sidebar-text-active: #059669;
 4  --sidebar-item-active-bg: #ecfdf5;
 5  --sidebar-child-text-active: #059669;
 6}
 7
 8[data-theme="dark"] {
 9  --sidebar-text-active: #34d399;
10  --sidebar-item-active-bg: #064e3b;
11  --sidebar-child-text-active: #34d399;
12}
 1/* 森林绿主题 */
 2:root {
 3  --sidebar-text-active: #047857;
 4  --sidebar-item-active-bg: #d1fae5;
 5  --sidebar-child-text-active: #047857;
 6}
 7
 8[data-theme="dark"] {
 9  --sidebar-text-active: #10b981;
10  --sidebar-item-active-bg: #022c22;
11  --sidebar-child-text-active: #10b981;
12}

紫色主题

 1/* 优雅紫色主题 */
 2:root {
 3  --sidebar-text-active: #7c3aed;
 4  --sidebar-item-active-bg: #f5f3ff;
 5  --sidebar-child-text-active: #7c3aed;
 6}
 7
 8[data-theme="dark"] {
 9  --sidebar-text-active: #a78bfa;
10  --sidebar-item-active-bg: #2e1065;
11  --sidebar-child-text-active: #a78bfa;
12}
 1/* 深紫色主题 */
 2:root {
 3  --sidebar-text-active: #6d28d9;
 4  --sidebar-item-active-bg: #ede9fe;
 5  --sidebar-child-text-active: #6d28d9;
 6}
 7
 8[data-theme="dark"] {
 9  --sidebar-text-active: #8b5cf6;
10  --sidebar-item-active-bg: #1e1b4b;
11  --sidebar-child-text-active: #8b5cf6;
12}

🔧 常见问题

样式不生效

1原因：CSS 文件未正确引入或变量未定义
2解决：
31️⃣ 检查 variables.scss 是否正确导入
42️⃣ 确认 CSS 变量命名是否正确
53️⃣ 清除浏览器缓存后刷新
64️⃣ 检查浏览器开发者工具查看实际应用的样式
1原因：暗色模式选择器错误或主题切换逻辑问题
2解决：
31️⃣ 确认使用 [data-theme="dark"] 选择器
42️⃣ 检查主题切换按钮是否正确设置 data-theme 属性
53️⃣ 验证暗色模式变量是否覆盖成功
1原因：选择器优先级不足或结构不匹配
2解决：
31️⃣ 检查 HTML 结构是否与选择器匹配
42️⃣ 增加选择器优先级，如使用 .simple-sidebar__children 前缀
53️⃣ 使用 !important 临时测试（不推荐长期使用）

配置生效检查清单

1✅ variables.scss 文件路径正确
2✅ CSS 变量命名符合规范
3✅ 亮色/暗色模式变量成对定义
4✅ 选择器与 HTML 结构匹配
5✅ 样式文件已正确引入主样式
6✅ 清除缓存后刷新页面

📝 配置模板速查

快速配置模板

1/* 最简配置：只修改选中颜色 */
2:root {
3  --sidebar-text-active: #2563eb;
4  --sidebar-item-active-bg: #eff6ff;
5}
 1/* 完整配置：修改所有样式 */
 2:root {
 3  /* 容器 */
 4  --sidebar-bg: #ffffff;
 5  --sidebar-border-color: #e5e7eb;
 6  
 7  /* 父目录 */
 8  --sidebar-text-color: #374151;
 9  --sidebar-text-hover: #111827;
10  --sidebar-text-active: #2563eb;
11  --sidebar-item-hover-bg: #f3f4f6;
12  --sidebar-item-active-bg: #eff6ff;
13  
14  /* 子目录 */
15  --sidebar-child-text-color: #4b5563;
16  --sidebar-child-text-hover: #1f2937;
17  --sidebar-child-text-active: #2563eb;
18  --sidebar-child-bg: #f9fafb;
19}
20
21[data-theme="dark"] {
22  /* 容器 */
23  --sidebar-bg: #1f2937;
24  --sidebar-border-color: #374151;
25  
26  /* 父目录 */
27  --sidebar-text-color: #d1d5db;
28  --sidebar-text-hover: #f9fafb;
29  --sidebar-text-active: #60a5fa;
30  --sidebar-item-hover-bg: #374151;
31  --sidebar-item-active-bg: #1e3a8a;
32  
33  /* 子目录 */
34  --sidebar-child-text-color: #9ca3af;
35  --sidebar-child-text-hover: #e5e7eb;
36  --sidebar-child-text-active: #60a5fa;
37  --sidebar-child-bg: #111827;
38}
1/* 仅修改暗色模式样式 */
2[data-theme="dark"] {
3  --sidebar-bg: #0f172a;
4  --sidebar-text-color: #94a3b8;
5  --sidebar-text-hover: #f1f5f9;
6  --sidebar-text-active: #38bdf8;
7  --sidebar-item-hover-bg: #1e293b;
8  --sidebar-item-active-bg: #0c4a6e;
9}

🎉 目录样式配置完成！

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

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