Skip to content

README.zh CN

Jump to bottom
menglingyu.213 edited this page Jan 23, 2026 · 1 revision

Github Issue TOC

简体中文 | English

这是 tofrankie/github-issue-toc 的一个 fork 版本，优化了侧边栏滚动体验。

Github Issue TOC 是一个 Chrome 浏览器扩展，可以自动为 GitHub 的 Issue 页面生成目录，并在右侧边栏显示，帮助用户快速定位感兴趣的内容章节。特别适合那些在 GitHub 上搭建博客、撰写长文章的用户。

✨ 本 Fork 版本的优化

  • 🔄 改进侧边栏滚动：整个右侧边栏（包括 TOC 和元数据）现在是一个 sticky 可滚动容器
  • 📌 始终可见：即使在滚动长 Issue 时，TOC 也始终保持可访问
  • 🎨 更好的用户体验：优化了滚动条样式，界面更加简洁
  • 🚀 独立滚动：右侧边栏与主内容区域独立滚动

✨ 特性

原有特性

  • 🚀 自动生成目录：自动识别 Issue 内容中的标题，生成结构化目录
  • 📍 智能定位：点击目录项即可快速跳转到对应章节
  • 🎯 高亮当前位置：滚动页面时自动高亮当前阅读位置
  • 🎨 原生样式：完美融入 GitHub 界面，体验一致
  • ⚡ 实时更新：Issue 内容变化时自动更新目录
  • 🌐 多层级支持：支持多级标题的层次结构展示

本 Fork 版本新增特性

  • 🔄 优化的侧边栏滚动：右侧边栏固定在视口中，可独立滚动
  • 📌 TOC 始终可见：页面滚动时 TOC 不会消失，始终可访问
  • 🎨 精致的滚动条：6px 细滚动条，与 GitHub 主题完美融合
  • 🚀 更好的用户体验：TOC 与 Assignees 等元数据自然排列，不会重叠

🛠️ 技术栈

  • 框架: Plasmo - 现代化的浏览器扩展开发框架
  • 前端: React 19 + TypeScript
  • 包管理: pnpm
  • 目标平台: Chrome MV3 / Edge MV3

📦 安装

方式 1：从 GitHub Release 下载（推荐）

  1. 访问 Releases 页面
  2. 下载 chrome-mv3-prod.zip 文件
  3. 解压 zip 文件
  4. 打开 Chrome 浏览器，访问 chrome://extensions/
  5. 开启右上角的「开发者模式」
  6. 点击「加载已解压的扩展程序」
  7. 选择解压后的 chrome-mv3-prod 文件夹

方式 2：本地构建安装

  1. 克隆仓库

    git clone https://github.com/exposir/github-issue-toc.git
cd github-issue-toc

  2. 安装依赖

    pnpm install

  3. 构建扩展

    pnpm build

  4. 加载扩展

    • 打开 Chrome 浏览器，访问 chrome://extensions/
    • 开启右上角的「开发者模式」
    • 点击「加载已解压的扩展程序」
    • 选择项目的 build/chrome-mv3-prod 目录

🚀 使用方法

  1. 安装扩展后，访问任意 GitHub Issue 页面
  2. 如果 Issue 内容包含标题（H1-H6），目录会自动显示在右侧边栏
  3. 点击目录项即可跳转到对应位置
  4. 滚动页面时，当前阅读位置会在目录中高亮显示

🏗️ 构建

# 构建 Chrome 扩展（包含 zip 压缩包）
pnpm build

# 构建 Edge 扩展（包含 zip 压缩包）
pnpm build:edge

构建产物位于 build/ 目录。

📁 项目结构

github-issue-toc/
├── src/
│   ├── background.ts          # 后台脚本，监听页面导航
│   ├── constants.ts           # 常量定义
│   ├── utils.ts              # 工具函数（标题查找、格式化等）
│   ├── contents/
│   │   ├── toc.tsx           # 目录组件主逻辑
│   │   └── toc.css           # 目录样式
│   └── popup/                # 扩展弹出窗口
├── assets/                   # 扩展图标等资源
├── screenshots/              # 演示截图
└── package.json

🔧 核心功能实现

标题识别

扩展会自动识别 Issue 内容区域（[data-testid="issue-body"]）中的所有标题元素（H1-H6），并为每个标题分配唯一 ID。

实时更新

使用 MutationObserver 监听 Issue 内容的变化，当内容更新时自动重新生成目录。

滚动定位

通过监听 scroll 事件，实时计算当前可视区域对应的标题，并在目录中高亮显示。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证。

👨‍💻 作者

exposir - GitHub

🙏 致谢

  • 感谢 tofrankie 创建了原始项目
  • 感谢所有为这个项目做出贡献的开发者！

如果这个扩展对你有帮助，欢迎给个 ⭐️ Star！

📝 GitHub Issue TOC | Made with ❤️ by exposir | GitHub | Issues | Releases

Clone this wiki locally