Configurable Sidebar toggle strategy

[mrlubos]

What version of starlight are you using?

0.38.3

What is your idea?

I'd like to expose a way to customize the sidebar open state toggle strategy. Currently, it's hard-coded in SidebarPersistState.ts.

Why is this feature necessary?

I prefer the way VitePress handles open states, i.e., only one group can be active at a time. It's way easier to spot the active group/item that way. This setting would allow users to get the same functionality.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[delucis]

SidebarPersistState actually does not handle the toggling — it only stores state to then restore it when loading a new page. The toggling is just regular HTML <details> behaviour.

In theory, it’s possible to use the name attribute on <details> to get “exclusive”, accordion-style behaviour on toggle. I’m not sure how likely we’d be to add support for that though: on the whole accordion behaviour can be confusing to users, causing content to jump around more than expected, and potentially hiding content they wanted to crossreference (e.g. have two groups open to compare their content and decide what’s the most relevant).

There’d also be some decisions to make about behaviour with nested groups — which might complicate things and prevent it working using only name because presumably expanding a nested group shouldn’t collapse its parent.

So overall, I’m not sure this would be a good candidate for a built-in option and maybe something to implement with a Sidebar override, which could be published as a plugin/package for others to use if there’s interest.

[mrlubos]

@delucis Totally understandable and custom is what I'm landing on as well. Honestly this is the only part that is confusing to me so I'd love to read any threads related to this functionality. For my part I think VitePress nailed this one – I'm looking to use sidebar as the current state marker.

The Astro behavior confuses me because navigating to pages through the pagination buttons doesn't work the same as clicking through sidebar, i.e., it won't automatically expand the group. The Astro demo is pretty close except it does NOT remember when I close a group and refresh, at least on mobile.

I'll keep playing with it, thank you for the context!

[trueberryless]

There’d also be some decisions to make about behaviour with nested groups — which might complicate things and prevent it working using only name because presumably expanding a nested group shouldn’t collapse its parent.

Wouldn't it be possible to just set equal names to all groups on the same tree layer? In other words: the height of the group decides its details name. So basically top-level groups get e.g. a details-1 name, all groups which are direct children of them get a details-2 name, and so on. That way, the parent / child groups never affect each other. And since only one parent group can be opened at a time, effects between child groups within different parent groups are not visible. Or am I missing something here?

What needs discussion is: Which group should open per default? None? The first? Depending on the collapse option? Personally, I would like to respect the collapse option, but as it is false per default, it would currently mean that we enforce that the user sets it to true on all but one child group or we don't force anything and rely on the specification in such cases:

If multiple grouped <details> elements are given the open attribute, only the first one in the source order will be rendered open. - MDN

---

So overall, I’m not sure this would be a good candidate for a built-in option and maybe something to implement with a Sidebar override, which could be published as a plugin/package for others to use if there’s interest.

I agree with this. Not having all groups and page links (titles) visible at once is the biggest counterargument in my opinion.