Feature Request: Multiple Sidebar Support

[Faf4a]

What version of starlight are you using?

0.9.0

What is your idea?

Add the support of multiple sidebar instances for better navigation.

Similar feature to what docusaurus currently provides, which basically allows you to assign specific sidebars to specific routes/endpoints and/or documents of your site.

Frontmatter (concept)

---
title: About this project
sidebar:
  group: <sidebarInstance>
---

In your astro config you'd then define the sidebars like the way you did before but you add some kind of name/Identifier to it.

Why is this feature necessary?

Would be basically a QoL change which would allow users to structure their documentation better.

As Starlight (as of this date) doesn't have a navbar where users are able to freely navigate between routes it wouldn't be the most ideal thing to add (as of now) in my opinion.

Do you have examples of this feature in other projects?

• Docusaurus
• VuePress

Participation

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

[scarf005]

This would be very useful. for example, we need to display 4 sidebars of distinct domain (for Players, for Modders, for Developers, and for Translators) and without navbars available space gets depleted quickly.

[stereobooster]

Adding screenshots for clarity

[Faf4a]

I might add to this saying this might be the perfect opportunity to also add versioning, as this would basically be all it needs. Referring to issue #372.

As versioning would also need a separate sidebar (docs??) instance.

website
├── sidebars.json        # sidebar for the current docs version
├── docs                 # docs directory for the current docs version
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello
├── versions.json        # file to indicate what versions are available
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

(structure from docusaurus)

This could be adapted and used similar for starlight.

[azan-n]

This could be adapted and used similar for starlight.

Just adding that we should explore other routes for generating sidebars and versioning instead of using a sidebars.json which I have found to be painful to use in large documentation just because of the large overhead of maintenance and the fact that most writers won't do the JSON editing.

Some reasons Nextra will be moving from a _meta.json to a ts file are listed here shuding/nextra#852

[Mat4m0]

Just to show another approach:

English "en" is the main language in the examples

docs
  sidebar1
    first+
      erstens__de.md 
      first__en.md 
    second.md
  sidebar2
    third.md
    fourth.md
blog
  post1.md
  post2+
    post__de.md
    post__en.md  

The + indicates that this is a multi-language folder, you can colocate your translations inside, having everything in one place.
I am using this structure in my Obsidian.md vault before exporting the files to Docusaurus, and it doesnt feel that bad.
But I am also not using versioning.

With:

• multiple docs
• multiple blogs
• multiple languages
• versioning

docs
├── next
│   ├── sidebar1
│   │   ├── first+
│   │   │   ├── erstens__de.md 
│   │   │   └── first__en.md 
│   │   └── second.md
│   └── sidebar2
│       ├── third.md
│       └── fourth.md
├── v1.0.0
│   ├── sidebar1
│   │   ├── first+
│   │   │   ├── erstens__de.md 
│   │   │   └── first__en.md 
│   │   └── second.md
│   └── sidebar2
│       ├── third.md
│       └── fourth.md
└── v0.9.0
    ├── sidebar1
    │   └── topic1+
    │       ├── erstens__de.md 
    │       └── first__en.md 
    └── sidebar2
        ├── third.md
        └── fourth.md
blog // first blog
├── post1.md
└── post2+
    ├── post__de.md
    └── post__en.md  

[LuHugo]

I'm coming from docusaurus, multiple sidebars are very useful for large documentation sites, I have over 30 different sidebars in my docusaurus project. An example is a documentation site like https://developer.mozilla.org/en-US/docs/Web where multiple sidebars are needed.

[TheGreatAxios]

For building large documentation sites this would be highly beneficial if it can be added.
There is already a PR open for this here: #687

While that may not be the best way to do it, seems like simply allowing the various folders within the src/content folder to represent different state trees of docs i.e

src/content/about
src/content/tutorials

[LuHugo]

Although it is possible to use such a structure, sidebars and pagination are not expected behavior. Pagination can now be overridden, but multilingual translation functions are not available externally.

[sanscontext]

Just chiming in because the ability to specify a sidebar is critical for our project, and would block us migrating. I would advise decoupling this from the versioning discussion, because for certain structures this would be a complete solution. (I have a folder that's v2 and a nav bar specific to that version, same with v3.)

[fmunteanu]

I'm into same boat. My Hugo site is designed to accommodate multiple projects, each project having their own header and sidebar, pretty much like the official https://docs.astro.build work, the title adds the docs, while the sidebar menus are different. I see @lorenzolewis did some work in this area, can his work related to multiple sidebars and navlinks be integrated into starlight project?

[zmaril]

Throwing my hat in the ring here, this is very much something I would like starlight to offer.

[ksteh]

This is something I am really looking forward to as well. In our use case, as we are preparing user guide for admin and employee to use our system, and we will need to have different sidebar menus for different user type.

[liam-s4s]

Also requesting this issue, would be really nice to have this docusaurus feature.

[BuckyBuck135]

Hello,
I would also love to see this feature implemented for QoL. It would cut down on a lot of overriding.

[carcigenicate]

Just in case people missed it, the linked PR gives an example of how to get this to work pretty simply. Their example just needs to cut off the path so only the top-level segment is considered (what we want for our case):

#687 (comment)

[HiDeoo]

Sharing another plugin based approach I made that allows to split documentation project into different sections, each with its own sidebar and landing page (and also supports external links): starlight-sidebar-topics

[trueberryless]

I can tell you, this plugin is awesome! If you prefer a dropdown, you can also use this plugin. It's based on HiDeoo's wunderful creation!