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.)