Sidebar folders order depends on their page order property

[cbontems]

What version of starlight are you using?

0.14.0

What version of astro are you using?

3.6.4

What package manager are you using?

pnpm

What operating system are you using?

Mac

What browser are you using?

Chrome

Describe the Bug

As discussed on Discord,

Structure:
 - docs/
    - category/
      - folder-1/
        - page-1.md
        - page-2.md
      - folder-2/
        - page-1.md
        - page-2.md

If I give my folder-1/page-1.md an order property of 10, and my folder-2/page-1.md an order property of 5, I end-up with my folder-2 being ranked above folder-1 in my sidebar.

Said differently, autogenerated folders are sorted according to the order of the first page in the directory.

In the stackblitz example linked below, in the fruits directory, the banana subdirectory comes before the apples subdirectory because it has a page with order 1, when apples has a page with order 5.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-dssfwv?file=src%2Fcontent%2Fdocs%2Ffruits%2Fbananas%2Flatundan.md

Participation

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

[cbontems]

I just started looking at a potential solution, but found this comment:

/**
 * Get the sort weight for a given route or directory. Lower numbers rank higher.
 * Directories have the weight of the lowest weighted route they contain.
 */
 function getOrder(routeOrDir: Route | Dir): number {

for the getOrderfunction in utils/navigation.ts so it looks like it is the expected behaviour for now.

This still look like a problem for me, as I don't want to check potential impact on other folders when I define order between pages inside a given folder.

Here is my use case to illustrate:

When work in a directory, i start by odering my pages by increments of 10.

• First page is order 10
• Second page is order 20
• Etc.

This way, when I need to insert a page later, I can do so without renumbering all pages.

• New Page order 15 will be inserted between pages 1 and 2.

Now, the problem is when I want to insert a page first in one folder. I will give it order 5, and by doing so, Starlight will not only insert my page first, but will also place this folder on top of my sidebar, which is not what I want.

[stavros-k]

In addition, nested directories cannot have custom labels.
eg a dir named my-folder cannot be shown as My Folder unless you manually add the links.

My suggestion would be to have something simillar on how docusaurus do.

• index.md(x) with frontmatter. which will also make the directory, a page
  so clicking on it on the sidebar willnot just collapse or un-collapse the tree, but show an actual page.
• A _config.yaml file (docusaurus has it as _category_.yml) which you can just add front-matter data, like title,order etc

Those should allow you to manually fix the above.
Another dirty solution to this, is to use 1000 range for the first dir, 2000 for the second.
So first dir will be 1010, 1020, etc
second dir will be 2010, 2020, etc

EDIT: I just saw:
#370
#1151

[apfelbox]

I am also highlight interested in both issues:

• Giving proper names to directories
• defining the order of folders and files in a directory, without impacting files inside these directories / other directories.

Is there already a solution for that?
Because right now you either have lowercase group labels with inconsistent sorting or a practically fully manual sidebar.

[jits]

Nuxt Content has a very nice way of supporting custom ordering, by allowing numeric prefixes in the filename, which it then ignores when generating the slug/ID.

[jharrell]

To throw 2c in:

I was looking at migrating a site to Astro, but my existing content all contains numeric prefixes 01-introduction 02-next-steps etc.

I was surprised that Starlight doesn't have the ability to ignore those prefixes as @jits mentioned.

[unional]

On the other hand, I have a related issue but within the same topic.

I have a folder containing release notes. I use autogenerate so that I don't have to manually add a new entry to the astro.config.mjs.

I named the files as yyyy-mm-dd.md e.g. 2024-11-02.md.

By default they are sorted in ascending order based on the file name.
I want to sort them in descending order as the latest release note should be the most significant, and user won't get the nav bar filled with all past releases so they can easily navigate to other part of the site.

Essentially this discussion: #1872

[trueberryless]

HiDeoo recently released a nice plugin which could simplify what you are wanting to achieve: https://starlight-auto-sidebar.netlify.app/metadata/#order

[trueberryless]

Nuxt Content has a very nice way of supporting custom ordering, by allowing numeric prefixes in the filename, which it then ignores when generating the slug/ID.

Since Starlight 0.35.0 added the generateId() callback function which enables customization of how URLs from filenames (entry) are transformed, you can now achieve the same behavior in Starlight (but without easy i18n unfortunately).

I wrote a blog post of how to do exactly that if anyone is still interested in such a setup: https://blog.trueberryless.org/blog/starlight-autogenerate-whole-sidebar/