Add Table of Contents sidebar for desktop and top section for mobile #1627
Conversation
...now it's the question of where should we put the button to open the ToC sidebar?
… + event actions to toggle ToC
…set in _config.yml
…ll desktop/tablet screens
…ty of the ToC sidebar
…avaScript, add more ARIA attributes, add docs
…no JavaScript env, customisable highlighting options, docs Also: - Added more specific toggle buttons for custom implementation - Replaced the Close text with an icon to close the panel in phone and small desktop/tablet view - Better implementation of the ToC panel in minimal view - Excluded the ToC panel in 404 view
…customisation, edit styling
|
Just to chime in since I've had a bit of radio silence & I've noticed you've been keeping this PR up to date: this is awesome work and looks great! I would love to merge this in soon. I have negative bandwidth now and would need to review this quite in-depth, both to evaluate the matrix of features you've added as well as doing an accessibility test. I want to do that relatively soon since this is such a great feature, but want to be transparent with my delays. I hope to have some more time soon. Apologies for the delay! |
|
“Absolutely love this branch! The way you implemented the TOC sidebar feels like watching a master carpenter fit the last dovetail—everything just slides into place. The opt-out logic is genius: instead of forcing the feature on every page, you trusted users to opt out when they need to, which is the perfect balance of power and politeness. And that media-query breakpoint tied to the sum of three variables? That’s not just responsive design, that’s responsive poetry. Thank you for making Jekyll feel like a first-class writing environment—this deserves to land in core!” |
|
Will the main content be centered when the sidebar is closed? After all, there's an additional table of contents on the right. |
|
On larger desktop screens where the navigation sidebar, the main content, and the Table of Contents sidebar have the room to display, the Table of Contents sidebar rests on the right side of the page content and follows you as you scroll down. It’s not possible to close that sidebar at this moment, many reference themes I saw just don’t do it, but I might consider making it collapsible if there’s a practical use case for it.
On smaller desktop and tablet screens, the ToC sidebar may appear as a floating panel (similar to MediaWiki’s) or an overlay sidebar, depending on which option you set up in _config.yml. It does not adjust the position/alignment of the page content displayed underneath it.
… On 27 Oct 2025, at 10:08, Eric ***@***.***> wrote:
Sephoration left a comment (just-the-docs/just-the-docs#1627)
Will the main content be centered when the sidebar is closed? After all, there's an additional table of contents on the right.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you authored the thread.Message ID: ***@***.***>
|
|
Hi there, |
|
I’m aware of it, but haven’t got around to fixing it. This has to do with the double underscores I put in some of the CSS class names, in order not to confuse them with the CSS classes in the page content.
… On 28 Oct 2025, at 20:09, Eric ***@***.***> wrote:
Sephoration left a comment (just-the-docs/just-the-docs#1627)
Hi there,
I just forked your project and everything runs perfectly—thank you for sharing it! I did notice two small console warnings: “Validate HTML (3.4)” and “Test CSS and JS (22.x)”. Could you kindly let me know if these appear on your side as well? I’d really appreciate any guidance you can offer.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you authored the thread.Message ID: ***@***.***>
|
|
Gonna study the implementation later today, it's really clean :> |
#1546 but with upstream changes
Kudos to allejo for making this possible with jekyll-toc (MIT).
Screenshots
Large desktops
Small desktops and Tablets
style: "float"(default)style: "side"Clicking on the overlay should also close the side panel.
Phones
I can make a Toggle ToC button next to the Toggle menu button or as a independent persistent button on the screen if that's needed.
Accessibility
ARIA attributes are added to all toggle buttons, and there's a new Skip to the Table of Contents button which automatically opens the panel (if hidden) and selects the first item in the ToC, if JavaScript is enabled.
For browsers with no JavaScript, toggle buttons to open the ToC panel on phones and small desktops should still work, although there would be no ARIA attribute updates, keyboard navigation (Skip to ToC link won't open the panel on phones and small desktops), and current section highlighting.
Keyboard navigation, I believe, is still somewhat limited. Feedback are welcome!
Breaking changes
IDs and classes that are affected by this change:
.visually-hidden.__container.side.float.__content#__aside#__aside-btn.__aside-btn.close-btn.close-icon.close-text.arrow-down-icon.toc-btn-sm.toc-btn-sm-text.current-heading.toc-btn-md.__page-actions.aside-overlayDiscussions and help needed
:has)$content-widthto take up the remaining space of$toc-widthFeedback are also welcome on accessibility, ToC behaviour on mobile and replacing the panel with a custom implementation.
Special thanks and Acknowledgments