# Github Issue TOC

简体中文 | [English](./README.md)

> **这是 [tofrankie/github-issue-toc](https://github.com/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](https://www.plasmo.com/) - 现代化的浏览器扩展开发框架
- **前端**: React 19 + TypeScript
- **包管理**: pnpm
- **目标平台**: Chrome MV3 / Edge MV3

## 📦 安装

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

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

### 方式 2：本地构建安装

1. **克隆仓库**

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

2. **安装依赖**

   ```bash
   pnpm install
   ```

3. **构建扩展**

   ```bash
   pnpm build
   ```

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

## 🚀 使用方法

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

## 🏗️ 构建

```bash
# 构建 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](./LICENSE) 许可证。

## 👨‍💻 作者

**exposir** - [GitHub](https://github.com/exposir)

## 🙏 致谢

- 感谢 [tofrankie](https://github.com/tofrankie) 创建了原始项目
- 感谢所有为这个项目做出贡献的开发者！

---

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