feat: add TOC sidebar for README and Markdown files #36250

hamkido · 2025-12-26T15:51:28Z

Add floating TOC panel that displays table of contents for README and markdown files
Implement toggle button to show/hide TOC panel
Add localStorage persistence for TOC panel visibility state
Support both README in repo root and individual markdown file views
Add responsive design for mobile screens

for this issue #36249

- Add floating TOC panel that displays table of contents for README and markdown files - Implement toggle button to show/hide TOC panel - Add localStorage persistence for TOC panel visibility state - Support both README in repo root and individual markdown file views - Add responsive design for mobile screens

lunny · 2025-12-28T04:48:58Z

1 there is a special background color on the toc icon which is unnecessary.
2 It's very strange of the TOC sidebar's position which should be near the readme panel.

…ectionObserver - Replace window resize and scroll event listeners with a ResizeObserver to monitor changes in the document body. - Implement an IntersectionObserver for the file header to trigger TOC position updates based on its visibility. - This improves performance and responsiveness of the TOC sidebar in file views.

hamkido · 2025-12-28T08:02:14Z

1 there is a special background color on the toc icon which is unnecessary.

I have remove background: var(--color-hover);

2 It's very strange of the TOC sidebar's position which should be near the readme panel.

I have completed the new commit, and the effect is shown in the screenshot below. Please compile and test it, and if you find any issues, please let me know. I will fix them promptly.
readme

markdown files

lunny · 2025-12-28T19:49:46Z

1 there is a special background color on the toc icon which is unnecessary.

I have remove background: var(--color-hover);

2 It's very strange of the TOC sidebar's position which should be near the readme panel.

I have completed the new commit, and the effect is shown in the screenshot below. Please compile and test it, and if you find any issues, please let me know. I will fix them promptly. readme markdown files

The second issue has been resolved, but I believe the first one has not. Additionally, the icons shown in the README and in the file view are different. The file view icon should have a border to match the style of the other icons.

lunny · 2025-12-28T20:45:50Z

Regarding the sidebar naming, I think different file formats should be able to have their own sidebar content. At the moment, only Markdown supports a TOC sidebar. If we introduce some abstraction here, it would be much easier to support sidebars for other file formats in the future.

- Change references from TOC to sidebar in the file view and README rendering functions. - Update CSS classes and JavaScript functions to reflect the new sidebar implementation. - Ensure proper visibility and positioning of the sidebar in the file view context.

- Enhance sidebar positioning to ensure it aligns with the file header and does not exceed the content's bottom. - Implement logic to hide the sidebar when the file content is scrolled out of view. - Replace IntersectionObserver with a scroll event listener for updating sidebar position, improving performance and responsiveness.

- Add a new Header type to encapsulate header data for generating the sidebar TOC. - Update the rendering logic to utilize SidebarTocHeaders, providing a more flexible structure for TOC generation. - Implement extraction of headers from orgmode documents to populate SidebarTocHeaders. - Ensure backward compatibility by maintaining the legacy SidebarTocNode for existing functionality.

- Simplify the calculation of the sidebar's top position to ensure it aligns with the file header or sticks to the top of the viewport when necessary. - Remove redundant opacity handling and improve clarity in the sidebar's visibility logic. - Maintain the sidebar's position next to the content with a consistent gap.

hamkido · 2026-01-03T11:07:37Z

I recently had surgery, so I'll find time next weekend to address this.

- Dynamically calculate the maximum height of the sidebar to prevent it from extending below the segment bottom. - Implement logic to hide the sidebar when the available height is insufficient, improving user experience. - Ensure the sidebar's top position does not exceed the segment's top during scrolling.

…position updates - Utilize IntersectionObserver to enhance performance and avoid issues associated with scroll events. - Implement fine-grained position updates using multiple thresholds for better responsiveness during scrolling.

- Update comments in RenderContext to clarify the deprecation of SidebarTocNode in favor of SidebarTocHeaders. - Remove unnecessary blank line in RenderSidebarTocHTML function for improved code readability.

- Add border styling to the sidebar toggle button in file view to match other buttons. - Update hover state to change border color for improved visual feedback.

hamkido · 2026-01-15T22:06:07Z

Regarding the sidebar naming, I think different file formats should be able to have their own sidebar content. At the moment, only Markdown supports a TOC sidebar. If we introduce some abstraction here, it would be much easier to support sidebars for other file formats in the future.

Abstraction has been added.
Now any renderer just needs to set ctx.SidebarTocHeaders to automatically get sidebar TOC support.
Orgmode file format already uses this abstraction

but I believe the first one has not. Additionally, the icons shown in the README and in the file view are different. The file view icon should have a border to match the style of the other icons.

Are the current icons displayed correctly?

lunny · 2026-01-17T18:28:44Z

Could we remove SidebarTocNode directly? Since it's an internal method, why we need to keep compatible?

…endering - Eliminate the deprecated SidebarTocNode from RenderContext and related functions. - Update sidebar TOC rendering logic to exclusively use SidebarTocHeaders for improved clarity and maintainability. - Remove fallback logic for legacy TOC rendering to streamline the codebase.

hamkido · 2026-01-18T07:07:12Z

You're right, I've updated it - removed SidebarTocNode and the fallback logic entirely. Thanks for the suggestion!

modules/markup/sidebar_toc.go

Co-authored-by: Lunny Xiao <[email protected]> Signed-off-by: hamkido <[email protected]>

GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Dec 26, 2025

github-actions bot added modifies/go Pull requests that update Go code modifies/templates This PR modifies the template files modifies/frontend labels Dec 26, 2025

hamkido added 2 commits December 27, 2025 00:01

fix: use CSS variable for font-weight in TOC sidebar

098321f

Merge branch 'main' into main

f543ab2

hamkido and others added 3 commits December 28, 2025 15:22

Merge branch 'go-gitea:main' into main

1348cb0

feat: add TOC sidebar for README and Markdown files

2d7b11e

lunny added this to the 1.26.0 milestone Dec 28, 2025

hamkido added 4 commits January 1, 2026 08:29

hamkido added 7 commits January 16, 2026 04:07

fix: use requestAnimationFrame for smooth sidebar scroll tracking

4687803

fix: use correct segment selector for TOC sidebar positioning

55e2cd3

fix: lower TOC sidebar breakpoint to 768px for tablet support

cbbbf09

fix: use btn-octicon style for TOC toggle button

ba42ce0

fix: remove explicit icon size for TOC button to match other btn-octicon

548e7ba

fix: reset button default styles for btn-octicon

4267f69

hamkido force-pushed the main branch from f01dc7b to 4267f69 Compare January 15, 2026 21:10

hamkido added 2 commits January 16, 2026 05:15

refactor: clean up sidebar TOC structure comments

fd754aa

- Update comments in RenderContext to clarify the deprecation of SidebarTocNode in favor of SidebarTocHeaders. - Remove unnecessary blank line in RenderSidebarTocHTML function for improved code readability.

style: enhance sidebar toggle button appearance

dc873a7

- Add border styling to the sidebar toggle button in file view to match other buttons. - Update hover state to change border color for improved visual feedback.

lunny reviewed Jan 18, 2026

View reviewed changes

modules/markup/sidebar_toc.go Outdated Show resolved Hide resolved

Update modules/markup/sidebar_toc.go

1aea6c4

Co-authored-by: Lunny Xiao <[email protected]> Signed-off-by: hamkido <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: add TOC sidebar for README and Markdown files #36250

feat: add TOC sidebar for README and Markdown files #36250

hamkido commented Dec 26, 2025

Uh oh!

lunny commented Dec 28, 2025

Uh oh!

hamkido commented Dec 28, 2025

Uh oh!

lunny commented Dec 28, 2025

Uh oh!

lunny commented Dec 28, 2025

Uh oh!

hamkido commented Jan 3, 2026

Uh oh!

hamkido commented Jan 15, 2026

Uh oh!

lunny commented Jan 17, 2026

Uh oh!

hamkido commented Jan 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

feat: add TOC sidebar for README and Markdown files #36250

Are you sure you want to change the base?

feat: add TOC sidebar for README and Markdown files #36250

Conversation

hamkido commented Dec 26, 2025

Uh oh!

lunny commented Dec 28, 2025

Uh oh!

hamkido commented Dec 28, 2025

Uh oh!

lunny commented Dec 28, 2025

Uh oh!

lunny commented Dec 28, 2025

Uh oh!

hamkido commented Jan 3, 2026

Uh oh!

hamkido commented Jan 15, 2026

Uh oh!

lunny commented Jan 17, 2026

Uh oh!

hamkido commented Jan 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants