feat(sidebar): normalize page links and control root chevrons by sy-records · Pull Request #2790 · docsifyjs/docsify

sy-records · 2026-08-21T06:19:23Z

Summary

Normalize link-only paragraphs in loose sidebar lists from <li><p><a> to <li><a>
Ensure sidebar links render consistently regardless of the Markdown list marker or list tightness
Preserve text-only paragraphs used as sidebar group titles
Add sidebar-chevron-root-hidden to hide chevrons on root-level page links and group titles
Simplify active, expanded, and collapsed sidebar CSS by removing loose-list compatibility selectors
Add regression coverage for normalized DOM, active highlighting, chevron states, and collapsing
AddcollapsibleSidebarGroups

Usage

<body class="sidebar-chevron-right sidebar-chevron-root-hidden">

Related issue, if any:

#2784 (comment)

What kind of change does this PR introduce?

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 · 2026-08-21T06:19:33Z

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

Project	Deployment	Actions	Updated (UTC)
docsify-preview	Ready	Preview	Aug 24, 2026 12:30pm

…essibility fix #2784 (comment)

…ble root groups

paulhibbitts · 2026-08-24T13:47:15Z

Hi @sy-records , your new collapsibleSidebarGroups config is awesome and works super well!

The PR preview build (with collapsibleSidebarGroups disabled by default) vs. released v5 now look identical:
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#/

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

And now, the PR preview build with collapsibleSidebarGroups set to true: 🚀
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&collapsibleSidebarGroups=true

NOTE: For an unknown reason the chevrons seem to shift a bit once collapsibleSidebarGroups is enabled - there seems to be a bit of extra padding added to the right side of the sidebar that causes the shift. Can you replicate that in your end?

I will more fully test things later today but just wanted to share initial results - great work 🙌🏼

paulhibbitts · 2026-08-24T15:38:26Z

Ok @sy-records I've updated the earlier CodeSandbox with this PR Preview Build:
https://codesandbox.io/p/sandbox/black-https-hj7935

I tested the new collapsibleSidebarGroups being not set, false and true and all worked well.

I confirmed the earlier issue of slight shifting to the right on chevrons when collapsibleSidebarGroups is enabled, and can confirm extra padding is present which looks like the cause:

I was also able to test <body class="sidebar-chevron-right sidebar-group-box sidebar-chevron-root-hidden"> to suppress the display of chevrons.

So everything is looking good except for the shifted chevrons issue.

sy-records · 2026-08-25T02:30:51Z

The link you provided seems to have a problem, but I compared all three and didn't find any issues.

https://preview.docsifyjs.org/#/?id=docsify
https://docsify.js.org/#/?id=docsify
https://docsify-preview-git-feat-chevron-docsifyjs.vercel.app/preview/#/?id=docsify

paulhibbitts · 2026-08-25T03:32:50Z

Oh that's good to hear @sy-records ! After seeing your other examples I went back and found that the reason for the shift in my example was I had this element on the sidebar:

<form action="https://github.com/paulhibbitts/docsify-this-open-publishing-site/generate" target="_blank">
  <input type="submit" value="Use this Template on GitHub" style="cursor: pointer;margin-top:12px;padding:6px;width:250px;background-color:#FFFFFF;border:1px solid #0374B5;border-radius:.25rem;color:#0374B5;display:inline-block;font-family:system-ui,sans-serif;text-align:center;text-decoration:none;font-size:16px;-webkit-text-size-adjust:none;mso-hide:all;" />
</form>

I will try to dig into why this caused the shift but once I removed that element I was able to remove the shift so that is good news!

paulhibbitts

After removing the added form element in my own example the shifting noticed earlier was thought to be removed but it is still present in my own example:

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

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

https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/test-docsify-this-multiple-page-open-publishing-site/main&homepage=home.md&sidebar=true&loadSidebar=_sidebar.md&hide-credits=true&core-theme-styles=true#/ (V5 release)

I will try to nail down the reason tomorrow and get back to you @sy-records .

sy-records · 2026-08-25T04:43:04Z

I see. To prevent the sidebar indentation from jumping, I added this, which caused the issue.

docsify/src/themes/shared/_sidebar.css

Line 188 in 5099294

scrollbar-gutter: stable;

You can reproduce this by expanding or collapsing Customization.

I recommend accepting this change in position.

paulhibbitts · 2026-08-25T16:21:00Z

Thanks for the additional information @sy-records , I now better understand the need of this minor shift.

During my testing, I noticed that Firefox the shift is more pronounced, could you please confirm that you can replicate that too? Based on this, I found this CSS reduces the shift only in Firefox - maybe it might be a useful reference for you:

@supports (-moz-appearance: none) {
  .sidebar {
    scrollbar-width: thin;
  }
}

feat(sidebar): normalize links and add root chevron control

c9e336d

feat(sidebar): replace group-title with group-toggle for improved acc…

73b03c7

…essibility fix #2784 (comment)

vercel Bot deployed to Preview August 22, 2026 14:17 View deployment

sy-records mentioned this pull request Aug 22, 2026

feat(sidebar): add collapsible root sidebar groups #2784

Merged

15 tasks

feat(sidebar): add collapsibleSidebarGroups configuration for expanda…

ead5483

…ble root groups

vercel Bot deployed to Preview August 24, 2026 12:02 View deployment

sy-records requested a review from paulhibbitts August 24, 2026 12:03

docs(configuration): sort sidebar options alphabetically

dac8a68

vercel Bot deployed to Preview August 24, 2026 12:30 View deployment

paulhibbitts approved these changes Aug 25, 2026

View reviewed changes

paulhibbitts self-requested a review August 25, 2026 03:36

Navigation Menu

Uh oh!

Uh oh!

feat(sidebar): normalize page links and control root chevrons - #2790

feat(sidebar): normalize page links and control root chevrons#2790
sy-records wants to merge 4 commits into
developfrom
feat/chevron

sy-records commented Aug 21, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

paulhibbitts commented Aug 24, 2026 •

edited

Loading

Uh oh!

paulhibbitts commented Aug 24, 2026 •

edited

Loading

Uh oh!

sy-records commented Aug 25, 2026

Uh oh!

paulhibbitts commented Aug 25, 2026

Uh oh!

paulhibbitts left a comment •

edited

Loading

Uh oh!

sy-records commented Aug 25, 2026

Uh oh!

paulhibbitts commented Aug 25, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

sy-records commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

Related issue, if any:

What kind of change does this PR introduce?

For any code change,

Does this PR introduce a breaking change?

Tested in the following browsers:

Uh oh!

vercel Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paulhibbitts commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paulhibbitts commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sy-records commented Aug 25, 2026

Uh oh!

paulhibbitts commented Aug 25, 2026

Uh oh!

paulhibbitts left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sy-records commented Aug 25, 2026

Uh oh!

paulhibbitts commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sy-records commented Aug 21, 2026 •

edited

Loading

vercel Bot commented Aug 21, 2026 •

edited

Loading

paulhibbitts commented Aug 24, 2026 •

edited

Loading

paulhibbitts commented Aug 24, 2026 •

edited

Loading

paulhibbitts left a comment •

edited

Loading

paulhibbitts commented Aug 25, 2026 •

edited

Loading