Github Issue TOC

简体中文 | English

This is a fork of 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 - 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
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

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

2. Install dependencies

   pnpm install

3. Build the extension

   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

# 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.

👨‍💻 Author

exposir - GitHub

🙏 Acknowledgments

• Thanks to 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!