文章目录模块优化说明
功能特性
1. 智能页面识别
- 只在文章页面显示:自动识别文章页面,排除首页、分类页、标签页、归档页等
- 多重判断机制:通过URL路径、页面元素、文章元数据多重验证
- 避免干扰:确保目录只在需要的地方出现
2. 现代化卡片风格
- 圆角边框和阴影效果
- 悬停动画和过渡效果
- 支持深色模式自动适配
- 响应式设计,适配各种屏幕尺寸
3. 智能交互
- 点击标题可展开/收起目录
- 移动端默认收起,桌面端默认展开
- 平滑滚动到对应标题位置
- 自动高亮当前阅读位置
4. 阅读进度指示
- 左侧进度条显示阅读进度
- 滚动时实时更新
- 视觉化阅读体验
5. 响应式布局
- 桌面端 (≥1200px): 右侧悬浮固定
- 平板端 (768px-1199px): 文章内容区域内嵌
- 移动端 (<768px): 优化间距,默认收起
文件结构
1 | source/assets/ |
使用方法
自动启用
目录功能会自动检测文章页面和标题:
- 页面识别:只在文章页面显示,自动排除首页、分类页、标签页、归档页、关于页等
- 标题检测:如果文章中存在标题(h1-h6),会自动生成目录
页面识别逻辑
系统通过以下方式判断是否为文章页面:
- URL路径检查:排除
/categories/、/tags/、/archives/、/等特殊路径 - 页面元素识别:检查是否存在文章特有的DOM元素
- 元数据验证:确认存在文章日期、分类等元数据
手动控制
- 展开/收起: 点击目录标题
- 跳转: 点击目录项会平滑滚动到对应位置
- 移动端: 目录默认收起,点击可展开
自定义配置
修改样式
编辑 source/assets/css/custom-toc.css 文件,可以自定义:
- 颜色主题
- 字体大小
- 间距布局
- 动画效果
修改行为
编辑 source/assets/js/custom-toc.js 文件,可以调整:
- 滚动偏移量(默认80px)
- 展开/收起行为
- 响应式断点
兼容性
- 支持所有现代浏览器
- 兼容 IE11+
- 移动端Safari、Chrome、Firefox测试通过
- 适配Landscape-x主题
故障排除
目录不显示
- 检查文章是否包含h1-h6标题
- 确认CSS和JS文件已正确引入
- 查看浏览器控制台是否有错误
样式异常
- 检查主题CSS是否与自定义样式冲突
- 确认浏览器缓存已清除
- 验证CSS文件路径是否正确
功能失效
- 检查JavaScript文件是否正确加载
- 确认没有JS错误阻止执行
- 验证文章内容区域选择器是否匹配
更新日志
- v1.0.0: 初始版本,包含基础目录功能
- 现代化卡片风格设计
- 响应式布局适配
- 智能交互和进度显示

