Fork me on GitHub

文章目录模块优化说明

功能特性

1. 智能页面识别

  • 只在文章页面显示:自动识别文章页面,排除首页、分类页、标签页、归档页等
  • 多重判断机制:通过URL路径、页面元素、文章元数据多重验证
  • 避免干扰:确保目录只在需要的地方出现

2. 现代化卡片风格

  • 圆角边框和阴影效果
  • 悬停动画和过渡效果
  • 支持深色模式自动适配
  • 响应式设计,适配各种屏幕尺寸

3. 智能交互

  • 点击标题可展开/收起目录
  • 移动端默认收起,桌面端默认展开
  • 平滑滚动到对应标题位置
  • 自动高亮当前阅读位置

4. 阅读进度指示

  • 左侧进度条显示阅读进度
  • 滚动时实时更新
  • 视觉化阅读体验

5. 响应式布局

  • 桌面端 (≥1200px): 右侧悬浮固定
  • 平板端 (768px-1199px): 文章内容区域内嵌
  • 移动端 (<768px): 优化间距,默认收起

文件结构

1
2
3
4
5
6
source/assets/
├── css/
│ └── custom-toc.css # 目录样式文件
├── js/
│ └── custom-toc.js # 目录交互功能
└── README-TOC.md # 本说明文件

使用方法

自动启用

目录功能会自动检测文章页面和标题:

  • 页面识别:只在文章页面显示,自动排除首页、分类页、标签页、归档页、关于页等
  • 标题检测:如果文章中存在标题(h1-h6),会自动生成目录

页面识别逻辑

系统通过以下方式判断是否为文章页面:

  1. URL路径检查:排除 /categories/、/tags/、/archives/、/ 等特殊路径
  2. 页面元素识别:检查是否存在文章特有的DOM元素
  3. 元数据验证:确认存在文章日期、分类等元数据

手动控制

  • 展开/收起: 点击目录标题
  • 跳转: 点击目录项会平滑滚动到对应位置
  • 移动端: 目录默认收起,点击可展开

自定义配置

修改样式

编辑 source/assets/css/custom-toc.css 文件,可以自定义:

  • 颜色主题
  • 字体大小
  • 间距布局
  • 动画效果

修改行为

编辑 source/assets/js/custom-toc.js 文件,可以调整:

  • 滚动偏移量(默认80px)
  • 展开/收起行为
  • 响应式断点

兼容性

  • 支持所有现代浏览器
  • 兼容 IE11+
  • 移动端Safari、Chrome、Firefox测试通过
  • 适配Landscape-x主题

故障排除

目录不显示

  1. 检查文章是否包含h1-h6标题
  2. 确认CSS和JS文件已正确引入
  3. 查看浏览器控制台是否有错误

样式异常

  1. 检查主题CSS是否与自定义样式冲突
  2. 确认浏览器缓存已清除
  3. 验证CSS文件路径是否正确

功能失效

  1. 检查JavaScript文件是否正确加载
  2. 确认没有JS错误阻止执行
  3. 验证文章内容区域选择器是否匹配

更新日志

  • v1.0.0: 初始版本,包含基础目录功能
  • 现代化卡片风格设计
  • 响应式布局适配
  • 智能交互和进度显示