# Github Issue TOC

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

> **This is a fork of [tofrankie/github-issue-toc](https://github.com/tofrankie/github-issue-toc) with enhanced sidebar scrolling experience.**

Github Issue TOC is a Chrome extension that automatically generates a table of contents on Github's Issue page and displays it in the right sidebar, helping users to quickly locate sections of content of interest, especially for those who build blogs and write long articles on Github.

## ✨ Enhancements in This Fork

- **🔄 Improved Sidebar Scrolling**: The entire right sidebar (including TOC and metadata) is now a sticky scrollable container
- **📌 Always Visible**: TOC remains accessible even when scrolling through long issues
- **🎨 Better UX**: Optimized scrollbar styling for a cleaner look
- **🚀 Independent Scrolling**: Right sidebar scrolls independently from the main content

## ✨ Features

### Original Features

- 🚀 **Auto-generate TOC**: Automatically identifies headings in Issue content and generates a structured table of contents
- 📍 **Smart Navigation**: Click on TOC items to quickly jump to corresponding sections
- 🎯 **Highlight Current Position**: Automatically highlights the current reading position when scrolling
- 🎨 **Native Styling**: Perfectly integrates with GitHub's interface for a consistent experience
- ⚡ **Real-time Updates**: Automatically updates TOC when Issue content changes
- 🌐 **Multi-level Support**: Supports hierarchical display of multi-level headings

### New Features in This Fork

- 🔄 **Optimized Sidebar Scrolling**: Right sidebar is fixed in viewport and scrolls independently
- 📌 **Always Visible TOC**: TOC remains accessible and doesn't disappear when scrolling
- 🎨 **Refined Scrollbar**: 6px thin scrollbar that perfectly matches GitHub's theme
- 🚀 **Better UX**: TOC and Assignees/metadata are naturally arranged without overlap

## 🛠️ Tech Stack

- **Framework**: [Plasmo](https://www.plasmo.com/) - Modern browser extension development framework
- **Frontend**: React 19 + TypeScript
- **Package Manager**: pnpm
- **Target Platform**: Chrome MV3 / Edge MV3

## 📦 Installation

### Option 1: Download from GitHub Release (Recommended)

1. Visit the [Releases page](https://github.com/exposir/github-issue-toc/releases/latest)
2. Download the `chrome-mv3-prod.zip` file
3. Extract the zip file
4. Open Chrome and visit `chrome://extensions/`
5. Enable "Developer mode" in the top right corner
6. Click "Load unpacked"
7. Select the extracted `chrome-mv3-prod` folder

### Option 2: Build from Source

1. **Clone the repository**

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

2. **Install dependencies**

   ```bash
   pnpm install
   ```

3. **Build the extension**

   ```bash
   pnpm build
   ```

4. **Load the extension**
   - Open Chrome browser and visit `chrome://extensions/`
   - Enable "Developer mode" in the top right corner
   - Click "Load unpacked"
   - Select the `build/chrome-mv3-prod` directory

## 🚀 Usage

1. After installing the extension, visit any GitHub Issue page
2. If the Issue content contains headings (H1-H6), the TOC will automatically appear in the right sidebar
3. Click on TOC items to jump to the corresponding position
4. When scrolling the page, the current reading position will be highlighted in the TOC

## 🏗️ Build

```bash
# Build Chrome extension (includes zip package)
pnpm build

# Build Edge extension (includes zip package)
pnpm build:edge
```

Build artifacts are located in the `build/` directory.

## 📁 Project Structure

```
github-issue-toc/
├── src/
│   ├── background.ts          # Background script, monitors page navigation
│   ├── constants.ts           # Constants definition
│   ├── utils.ts              # Utility functions (heading search, formatting, etc.)
│   ├── contents/
│   │   ├── toc.tsx           # TOC component main logic
│   │   └── toc.css           # TOC styles
│   └── popup/                # Extension popup window
├── assets/                   # Extension icons and resources
├── screenshots/              # Demo screenshots
└── package.json
```

## 🔧 Core Implementation

### Heading Recognition

The extension automatically identifies all heading elements (H1-H6) in the Issue content area (`[data-testid="issue-body"]`) and assigns a unique ID to each heading.

### Real-time Updates

Uses `MutationObserver` to monitor changes in Issue content and automatically regenerates the TOC when content is updated.

### Scroll Positioning

Monitors `scroll` events to calculate the heading corresponding to the current visible area in real-time and highlights it in the TOC.

## 🤝 Contributing

Issues and Pull Requests are welcome!

1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Submit a Pull Request

## 📄 License

This project is licensed under the [MIT](./LICENSE) license.

## 👨‍💻 Author

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

## 🙏 Acknowledgments

- Thanks to [tofrankie](https://github.com/tofrankie) for creating the original project
- Thanks to all developers who contributed to this project!

---

If this extension helps you, feel free to give it a ⭐️ Star!