Closed Faf4a closed 11 months ago
Adding screenshots for clarity
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.
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 https://github.com/shuding/nextra/issues/852
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:
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
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.
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)
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?
Participation