Allow sidebar groups to have their own content

[lucasmdjl]

What version of starlight are you using?

0.28.3

What is your idea?

Allow groups in the sidebar to not just group pages together, but also have a page of their own you can read when you click the group.

Why is this feature necessary?

Right now, you can have an index.mdx in a group and with the automatic configuration, it gets translated into a new page with the slug of the group, the title of the group, but a different entry in the sidebar. I think, I would be cleaner to have the index.mdx of the group (if present) be a page associated with the group itself, not just another page inside the group. This will help introduce different sections of the documentation in a safer and more concise way. For instance, the approach I'm using in my documentation is to label index as Overview, and then also manually edit the prev and next attributes of the following and previous pages to be the section name, which can lead to errors when pages are reordered or if the section is renamed.

Do you have examples of this feature in other projects?

• https://docusaurus.io/docs/docs-introduction
• https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-reference.html

Participation

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

[HiDeoo]

Thanks for the feedback.

Just for reference and add some initial context to the discussion, linking to this comment which describes the current reasoning regarding the current behavior:

In particular, we’ve had questions before about making the heading of a sidebar group also a link to the index page, but I think this results in confusing UX. Docusaurus does this and you essentially end up with an entry that does different things depending where you click on it:

click here to go to page
     ↓
Group title    >
               ↑
    click here to expand group

[lucasmdjl]

Hi, thanks for the link to that comment.

I can see why it could be a bit confusing to have a click do different things when clicking in the name and clicking on the arrow, though I personally haven't found it confusing when I've encountered it.

However, I think the current approach of having a child page with the same name as the group can be confusing too, and to be honest I have never seen it on a documentation website. Also, another issue with this is that the urls and the sidebar structure don't match, with the url of the index page being the parent url to its sidebar-sibling pages.

Since this feature request seems recurrent, why not support both designs? I.e. without an index page the group name could just collapse/expand, and with an index page it could also link to it.

[trueberryless]

Since this feature request seems recurrent, why not support both designs? I.e. without an index page the group name could just collapse/expand, and with an index page it could also link to it.

I really like this idea 💡, but this would make the design very inconsistent.

So we have to think of a way to either make ALL groups clickable or NO group (per site / per use case).

One potential idea I wanna share regarding this is:

By default make no group clickable. If the user adds one index file, autogenerate all MISSING index contents for all other groups...

But I think that this logic shouldn't be built-in Starlight, but rather an opt-in plugin.

I have an early plugin (more a thought at the moment) which creates automatic overview pages: https://github.com/trueberryless-org/starlight-automatic-overview-pages

But before I finish it, we need to think more about how to exactly achieve this... Maybe the plugin then exactly solves the feature request for the right use cases... 🤔

[anaxite]

I was think about this feature request, and wanted to share my thoughts.

In general, I find that lack of sidebar consistency is a big user experience challenge. If everything behaves the same it's fine, but if different sections have different behavior, users can get lost or frustrated. Starlight's behavior is consistent, which is a great default.

On the other hand, giving sidebar groups their own content may be worthwhile, given that:

• We all expect that different websites do different things, so we don't know website behavior until we start interacting with it.
• Starlight sidebar links and groups don't have a default underlined-blue URL styling, and top-level links have the same bold styling as groups; it's not necessarily clear what should be a link and what isn't.
• Sidebar groups that act as pages also enable certain breadcrumbs, index page processing, autogenerated page lists, and other use cases.

I have seen and used both kinds of sidebar groups, and appreciate both for different reasons. If I had the choice, I would suggest the following:

1. Retain the current sidebar group behavior as the main behavior to enforce consistency as a default.
2. Offer an option to enable sidebar groups as links.

But I can still live without the feature. We've got working docs site after all :)