GitHub README Table of Contents Injector

WHAT IT DOES

This script adds a floating table of contents (TOC) sidebar to GitHub README pages. When you view any README.md file on GitHub, the script automatically scans the document for all heading elements (h1 through h6), builds a hierarchical TOC based on the heading structure, and displays it as a sticky panel on the left or right side of the page. Each TOC entry is a clickable link that smoothly scrolls to the corresponding section. The current section is highlighted as you scroll, making it easy to track your position in long documents. The TOC includes a collapse/expand all button for nested sections, so you can focus on the top-level structure or drill down into subsections. The TOC updates automatically when you navigate between different README files.

WHERE IT RUNS

The script runs on GitHub README.md pages (github.com/*/*/blob/*/README.md). It works on both desktop and mobile views, and updates dynamically as you navigate between READMEs.

HOW TO USE

After installation, the settings panel appears on the left side of the screen with the gear emoji (⚙️). Open the panel to configure the script:

- The "Show table of contents" toggle enables or disables the TOC.

- Choose the TOC position from the dropdown: "Left side" or "Right side."

- Toggle "Collapse nested sections by default" to have all subheadings collapsed when the TOC loads.

The TOC appears automatically when you view a README. Click any TOC entry to scroll to that section. Use the ▼/▶ button to collapse or expand all nested sections. Click the ✕ button to hide the TOC.

TECHNICAL SECTION — REAL MECHANISM

The script detects README pages by checking the URL for /blob/ and README.md. It finds the rendered markdown content by looking for the .markdown-body, .readme, or .Box-body container. It extracts all heading elements (h1-h6) from the container, capturing each heading's text content and anchor ID. The heading list is then transformed into a hierarchical tree structure by iterating through the headings and tracking the current nesting level. Each heading is assigned a depth based on its h-level, and the script builds parent-child relationships accordingly. The TOC is rendered as a fixed-position container with a glassmorphism style. Each TOC item is an anchor link with a smooth scroll behavior. The scroll highlighting is implemented using a scroll event listener that checks each heading's offsetTop against the current scroll position, identifies the last heading above the viewport, and highlights the corresponding TOC link. The collapse/expand functionality toggles the display of nested unordered lists. The TOC position is controlled by setting the container's left or right CSS property based on user preference.

THE PANEL

The settings panel is built with BotGentz's BGPanel component. It is draggable via its header, allowing you to reposition it anywhere on the screen. The panel snaps to the left edge by default but can be moved freely. Click the gear emoji to collapse the panel into a small bubble, and click the bubble to expand it again. The panel remembers its position per page session. Press the Escape key to quickly close or minimize the panel. The panel includes a status flash bar that provides visual feedback when settings are changed or actions are performed. All settings save automatically via GM_setValue.

PLEASE NOTE

This script requires the free BotGentz browser extension to run. It does not function as a standalone Chrome extension and does not use chrome.* APIs. GitHub frequently updates its README rendering structure, which may affect the selectors used to find the markdown body and headings. If the TOC stops appearing, please check for script updates. The TOC is built from the rendered HTML headings—it requires the headings to have anchor IDs (which GitHub automatically generates). The script stores only your preferences (enabled state, position, and auto-collapse) via GM_setValue. No data is sent externally—all data is stored locally in your browser. The script never reads or writes password fields, hidden inputs, or file inputs. All DOM operations use safe methods (style properties, textContent, appendChild) and never use innerHTML.