Skip to content

README.md

Latest commit

 

History

History
213 lines (159 loc) · 6.12 KB

README.md

File metadata and controls

213 lines (159 loc) · 6.12 KB

Typecho 文章目录树插件 (TableOfContents)

一个功能强大、美观的 Typecho 文章目录树插件，自动提取文章标题生成导航目录。

✨ 主要特性

  • 🎯 自动生成目录 - 自动提取文章中的 H1-H6 标题
  • 📍 灵活定位 - 支持左侧固定、右侧固定、文章顶部三种显示位置
  • 🎨 美观设计 - 现代化 UI 设计，支持自定义主题颜色
  • 🔢 自动编号 - 可选的多级自动编号功能
  • 📱 响应式设计 - 完美适配桌面端、平板和移动端
  • ⚡ 平滑滚动 - 点击目录项平滑滚动到对应位置
  • 🎯 高亮当前 - 滚动时自动高亮当前阅读的章节
  • 🎭 折叠展开 - 支持目录的折叠和展开
  • ⚙️ 灵活配置 - 丰富的配置选项，满足不同需求

📦 安装方法

方法一：手动安装

  1. 下载本插件
  2. 将插件文件夹重命名为 TableOfContents
  3. 上传到 Typecho 的 usr/plugins/ 目录
  4. 在 Typecho 后台「控制台」→「插件」中启用插件

方法二：Git 克隆

cd usr/plugins/
git clone [仓库地址] TableOfContents

🔧 配置选项

在 Typecho 后台启用插件后，进入插件设置页面可以看到以下配置选项：

1. 目录位置

  • 左侧固定 - 目录固定在页面左侧
  • 右侧固定 - 目录固定在页面右侧（默认）
  • 文章顶部 - 目录显示在文章内容上方

2. 最小标题数量

设置触发显示目录的最小标题数量，默认为 3。当文章标题少于此数量时不显示目录。

3. 包含的标题层级

选择要包含在目录中的标题层级（H1-H6），默认包含 H2、H3、H4。

4. 自动编号

开启后会为目录项自动添加多级编号（如：1.1.1），默认开启。

5. 主题颜色

自定义目录的主题颜色，默认为 #4285f4（Google Blue）。

6. 移动端显示

选择是否在移动端显示目录，默认隐藏以优化移动端体验。

🎨 使用效果

左侧固定效果

┌──────────┬────────────────────────┐
│ 目录 [-] │      文章内容          │
│ 1. 章节1 │                        │
│   1.1    │                        │
│   1.2    │                        │
│ 2. 章节2 │                        │
└──────────┴────────────────────────┘

右侧固定效果

┌────────────────────────┬──────────┐
│      文章内容          │ 目录 [-] │
│                        │ 1. 章节1 │
│                        │   1.1    │
│                        │   1.2    │
│                        │ 2. 章节2 │
└────────────────────────┴──────────┘

顶部效果

┌─────────────────────────────────────┐
│ 目录 [-]                            │
│ 1. 章节1  1.1  1.2  2. 章节2       │
└─────────────────────────────────────┘
│                                     │
│          文章内容                   │
│                                     │

🛠️ 主题兼容性

插件会自动检测以下常见的文章容器选择器：

  • .post-content
  • .entry-content
  • .article-content
  • .content
  • article
  • .post

如果您的主题使用了其他选择器，可以在 Plugin.php 的第 366 行修改 articleSelectors 数组：

var articleSelectors = [".post-content", ".entry-content", ".your-custom-class"];

💡 使用技巧

1. 文章中使用标题

在 Markdown 或 HTML 编辑器中，正常使用标题标签：

Markdown:

## 第一章节
### 1.1 子章节
## 第二章节

HTML:

<h2>第一章节</h2>
<h3>1.1 子章节</h3>
<h2>第二章节</h2>

2. 自定义样式

如果需要自定义目录样式，可以在主题的 CSS 文件中覆盖以下类：

/* 自定义目录容器 */
#toc-container {
    background: #f8f9fa;
    border-radius: 12px;
}

/* 自定义链接颜色 */
#toc-list a {
    color: #333;
}

/* 自定义活动状态 */
#toc-list a.active {
    color: #ff6b6b;
    font-weight: bold;
}

3. 禁用特定文章的目录

如果某篇文章不想显示目录，可以在文章内容最前面添加：

<style>#toc-container { display: none; }</style>

🔍 常见问题

Q: 目录没有显示？

A: 请检查：

  1. 文章标题数量是否达到"最小标题数量"设置
  2. 是否在文章页面（而非列表页）
  3. 主题的文章容器选择器是否被正确识别

Q: 目录位置不合适？

A: 可以在插件设置中更改"目录位置"选项，或通过 CSS 调整 top、left、right 属性。

Q: 如何修改目录宽度？

A: 在主题 CSS 中添加：

#toc-container.toc-fixed-left,
#toc-container.toc-fixed-right {
    width: 300px; /* 修改为想要的宽度 */
}

Q: 移动端目录显示异常？

A: 建议在插件设置中将"移动端显示"设置为"隐藏"。

🚀 性能优化

  • 使用节流函数优化滚动监听，减少性能消耗
  • 仅在文章页面加载，不影响其他页面
  • CSS 使用硬件加速的 transform 属性
  • JavaScript 采用事件委托减少内存占用

📝 更新日志

v1.0.0 (2025-10-12)

  • 🎉 首次发布
  • ✨ 支持自动生成目录
  • 🎨 三种显示位置可选
  • 📱 响应式设计
  • 🔢 自动编号功能
  • ⚡ 平滑滚动和高亮

📄 开源协议

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

💖 支持

如果这个插件对您有帮助，欢迎 Star ⭐

Made with ❤️ for Typecho