feat(sidebar): add collapsible root sidebar groups

[sy-records]

Summary

Related issue, if any:

Fixes#900

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation content changes
• Other (please describe):

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

• Yes
• No

Tested in the following browsers:

• Chrome
• Firefox
• Safari
• Edge

[vercel]

@sy-records is attempting to deploy a commit to the Docsify Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docsify-preview	Ready	Preview	Aug 18, 2026 7:57am

[paulhibbitts]

Thanks for taking this long-requested feature on @sy-records !

Here is my test sandbox:
https://codesandbox.io/p/devbox/vibrant-brattain-hj7935

I am concerned that the introduction of using bold to mark new expandable/collapsible sections might be confusing for users and add visual complexity to the sidebar.

One alternative would be to use the existing Chevron indicators to show expandable/collapsible sections (with existing rotation behavior), and do so without little additional visual complexity. Here is a quick mockup:

What do you think?

[paulhibbitts]

You might also find this closed issue a helpful reference @sy-records : #1564

I am not suggesting additional functionality at this point, but the comment by jhildenbiddle was also quite insightful for future consideration re: initial expaned/collapsed state.

[sy-records]

The bold text represents the original logic; now it simply supports clicking to expand or collapse it and marks its status so you don’t have to click repeatedly when viewing it.

Using a V-shaped indicator will change the current style.

[paulhibbitts]

I am not sure I follow, if bold text is used, and is also in multiple locations, this will likely be confusing for users re: cue of feedback. If I understand correctly possible, I suggest we use the established chevon feedback which is also used by other similar sidebar navs like Docusaurus https://docusaurus.io/docs/category/guides.

If bold is only possible I suggest setting aside this feature as the downsides would outweigh the possible upsides to me.

[sy-records]

I added logic to the sidebar-chevron.

[paulhibbitts]

Oh that is starting to work much better @sy-records ! Sorry if I was not specific enough before but along with adding the Chevrons would be removing the bold styling. Once that is done, manually collapsible items will have a visual cue that they can expand/collapse and have the exact same style of the other items present in the sidebar as to not give any confusing feedback. This is going to be a great new feature!

[sy-records]

My previous idea was to keep it, because it comes from the style of v4 and v5, which is just to add an unfolding and folding function.

[paulhibbitts]

I am not sure for what context that style was used before (do you have an example?), but using it with the new expand/collapse feature does not seem to fit that well. I have not seen bold used in tandem with an expand/collapse behaviour.

Your addition of the chevrons works really well - could you give removing the bold a try and see how it looks/works? I think it should really unify the visual/UX design 🙂

[sy-records]

Users can override the bold style by setting --sidebar-group-title-font-weight.

--sidebar-group-title-font-weight:var(--font-weight);

What I mean is to keep it as is to highlight the hierarchical relationships.

[paulhibbitts]

Thanks for the additional information and context @sy-records , I did not realize the relationship to sidebar group titles - your screenshot was very helpful! Now that I see that, and there is an option to not bold as well, this combined chevron + optional bold approach looks good to me!

[paulhibbitts]

Thanks for the additional information and context @sy-records , I did not realize the relationship to sidebar group titles - your screenshot was very helpful! Now that I see that, and there is an option to not bold as well, this combined chevron + optional bold approach looks good to me!

[paulhibbitts]

Thanks very much @sy-records , this is looking very good! I've updated the sandbox to now use group boxes and use the CSS var you shared to unbold the titles - and added more dummy menu items:

https://codesandbox.io/p/sandbox/black-https-hj7935

This made me remember an previous Docsify v4 site I created with John Hildenbiddle's Themeable which I have now converted over to v5, where I "hacked" together collapsible sidebar items for a site with a fair number of pages:

https://docs.hibbittsdesign.org/#/

You can see that it is quite valuable to be be able to also set all items as collapsed to provide a nice UX for someone to first pick a high-level category, and then explore related items etc.

This made me regret my earlier comment about not considering setting the initial collapsed state for collapsible items, seen in PR 1563 🫤

Any possible options here from your viewpoint? Thanks very much!

[paulhibbitts]

Your new config to set all sidebar groups to be initially collapsed is awesome @sy-records!

One small naming suggestion though, collapseSidebar reads a bit ambiguous next to the existing hideSidebar option, since both could be read as affecting the whole sidebar panel. Since everywhere else in the implementation uses "group" (.group-title, data-group-id, #toggleSidebarGroup()), how about collapseSidebarGroups instead?

[paulhibbitts]

This is looking great @sy-records , here is the updated CodeSandbox with the latest PR Preview Build and as well testing the ability to set collapseSidebarGroups to true:
https://codesandbox.io/p/sandbox/black-https-hj7935

All is looking good!

[paulhibbitts]

Hi @sy-records , not sure if this is the best place or I should create a new issue for this - let me know!

I am starting to use the newest Docsify preview with my own Docsify-This test site, and have already run across some unintended consequences of the new collapsible sidebar being automatically applied, for example:

Docsify v5 release:

Docsify v5 Preview Build:

Note the bold group titles and new chevron icons appearing automatically, with no action taken by the user - this is of concern as we don't want to start changing the design of Docsify sites with no user confirmation/action.

Perhaps could we add a new config, set to false by default, to enable/disable collapsible sidebar items (i.e. sidebarGroupsCollapsible, false as default)? I think with this one change, no changes would occur on existing sites and users could then "opt-in" for the use of collapsible sidebar groups.

Alternatively, and I think the better long-term design, adopting the syntax @jhildenbiddle suggested in #1564 would also result in no change without user opt-in, and would remove the need for a config option altogether - both the already-shipped collapseSidebar initial-state setting and the sidebarGroupsCollapsible toggle I'm proposing above. Maybe this is still out-of-scope at this point, but still the best long-term solution to this issue I think.

* Text Heading (no expand/collapse)
* [Page 1](page1.md)
* [Page 2](page2.md)
+ Toggle Heading (click to expand)
+ [Page 1](page1.md)
+ [Page 2](page2.md)
- Toggle Heading (click to collapse)
- [Page 1](page1.md)
- [Page 2](page2.md)

I was not able to foresee this until I started to try out more possible Docsify test setups via Docsify-This.

Looking forward to hearing your thoughts, thanks very much Paul.

[sy-records]

Can you share the link?

My original idea for this feature was simply to allow the root sidebar to be collapsed and expanded without adding a chevron icon. That way, it would essentially be a hidden feature for users and wouldn't affect them in any way.

If the user doesn't want it, they can set ':class=no-chevron'

[Topic Three][three.md ':class=no-chevron']

[sy-records]

Technically, you can read the symbols via Marked's list_item.raw, but it is not recommended to treat *, +, and - as interactive semantics.

[paulhibbitts]

Hi @sy-records , the issue is more the unexpected change of previously non-bold items to bold. The addition of chevrons is also a visual change, but less noticeable. I reverted the collapsible sidebar group commit from my sync repo used for Docsify-This for this reason. Having done that, now I can use the Docsify-This production build vs. my preview build to show you before and afters.

Docsify-This without collapsible sidebar groups:
https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-multiple-page-open-publishing-site/main&homepage=home.md&sidebar=true&loadSidebar=_sidebar.md&hide-credits=true&core-theme-styles=true

Docsify-This Preview with collapsible sidebar groups:
https://preview.docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-multiple-page-open-publishing-site/main&homepage=home.md&sidebar=true&loadSidebar=_sidebar.md&hide-credits=true&core-theme-styles=true

As you can see, the now collapsible items are bold, which changes the visual appearance of Topic 3 with no user choice to do so. Chevrons are also added to two items, which is not ideal either but less of a visual change.

I hope the above very simple example shows the issue of unrequested changes happening to a user's docsify site. If a feature will change the visual design and behavior of a site we should make it opt-in, so no action will result in no site changes.

Possible ways to opt-in to this feature might be an additional config (i.e. sidebarGroupsCollapsible) set to false by default (maybe the simplest way?). Changing the markup required to activate collapsible items is another option, though as you noted, that's probably less ideal - and it has the same core problem: - is already the standard bullet character most existing sidebars use, so mapping it to "collapse by default" would silently apply the same unrequested bold/collapsible change to nearly every existing site, with no action taken by the user. Open to other approaches too!

Looking forward to hearing your thoughts, and anyone else here to chime in!

PS: For additional references, here is how several other doc generators handle this same situation:
https://vitepress.dev/reference/default-theme-sidebar#collapsible-sidebar-groups
https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-expansion

[sy-records]

You can try #2790. There are quite a few configuration options, so I'm using class names to distinguish them.

[paulhibbitts]

Thanks @sy-records , #2790 is a great step forward and solves the bold styling issue well!

That said, I'd still like to advocate for a fully opt-in approach, where no visual or behavioral changes happen unless a user explicitly chooses them - even with #2790, clicking now does something new on upgrade with no action taken, and there's still no way to fully disable the feature itself, only its visual presentation. In other words, a Docsify site with this additional feature should look and work identical to the current release UNTIL the user enables the new collapsible sidebar ability.

I think the earlier proposed sidebarGroupsCollapsible config (false by default) is likely still the most straightforward way to achieve that based on things so far, please let me know what you think.

[sy-records]

That's fine with me; I added collapsibleSidebarGroups.

[paulhibbitts]

Awesome, thank you @sy-records - this new feature is looking really great 🙏🏻