Refactor autogenerated sidebar groups

[HiDeoo]

Description

• This PR adds a new feature which has been discussed and approved here.

• Closes Groupless autogenarated sidebar links #3336

This PR removes the notion of "autogenerated sidebar groups" in favor of simply using "autogenerated sidebar links" which can be used in regular sidebar groups. As discussed in #3336, this simplifies the mental model around groups and also allows for use cases that were not possible before, such as having a sidebar entirely made of autogenerated links for a specific directory without having it nested inside a group.

For users, the gist of the change is:

{
    label: 'My group',
-   autogenerate: { directory: 'some-dir' },
+   items: [{ autogenerate: { directory: 'some-dir' } }],
}

Such refactor removes the 1:1 mapping that was previously available between an autogenerated sidebar group in the Starlight configuration and such autogenerated group in the Starlight route data. To address such change, the Starlight route data has been updated and many solutions are possible to address this, e.g. having multiple types (link, autolink, group, and autogroup). This PR has gone through multiple variations of such approach, and the current implementation does not introduce new types but rather adds an autogenerated property set to to true for links and subgroups that were autogenerated. Of course, other approaches are possible and feedback is welcome.

To make sure such change does not impact plugins with previous features that would no longer be possible due to the changes, I rewrote locally the starlight-auto-sidebar plugin, which was heavily relying on that 1:1 mapping and to my knowledge, may be one of the "largest" plugins tweaking sidebar route data for autogenerated groups with a large enough set of tests. I managed to rewrite it successfully while using the Starlight version from this PR and achieved the same results as before.

Note: I also addded a few tests for some behaviors that were not covered before and were impacted by this change, e.g. the collapsed state of autogenerated subgroups.

Remaining tasks

• Add changeset

[changeset-bot]

🦋 Changeset detected

Latest commit: ad5286c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	ad5286c
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/69fb3c7db5a0080008a79b26
😎 Deploy Preview	https://deploy-preview-3618--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/sidebar.mdx	Source changed, localizations will be marked as outdated.
en	reference/configuration.mdx	Source changed, localizations will be marked as outdated.
en	reference/frontmatter.md	Source changed, localizations will be marked as outdated.
en	reference/route-data.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[delucis]

I updated the branch to be aligned with main and noted a few things. Most were notes I can use myself, but one question would be good to get feedback on from you @HiDeoo!

[delucis]

I think this is in pretty good shape!

There’s this note-to-self #3618 (comment) that you might want to revisit @HiDeoo?

Otherwise, unless you think we should add any additional autogenerate metadata to the sidebar links structure, I’d love to get this out in the next minor release 🚀

[HiDeoo]

Pushed a new update adressing this comment and refactoring the previously exposed autogenerated: boolean property on route data to an autogenerate object with a directory property matching the configured autogenerated directory so we can discuss it with a concrete example.

I also included in a dedicated commit some changes adressing this previous note regarding type error location. I did that in a dedicated commit so it can be easily reverted as I think it may be getting out of hand and trying to fight TypeScript too much to get best possible error and locations. Not sure if the extra complexity is worth for a workaround that took me a few hours to even figure out and implement. We already have what I would qualify as quite good runtime validation with detailed error messages, and even migration steps. It also feels a bit fragile as it's relying on some specific TypeScript behavior that is not guaranteed to be stable.

[delucis]

Thanks for the updates @HiDeoo!

Re: the Typescript stuff — I don’t have too strong an opinion. It’s definitely getting very arcane and hard to understand with these subtle things like void vs never, but I’ll let you decide if you want to keep it or not.

[HiDeoo]

Pushed a few updates:

• Removed the TypeScript changes. While it refined the type error locations, I think it made the error even more obscure imo. The never type was already probably confusing but more common than void and could still guessed by just reading the error message. With the refactor, reading that something is "not assignable to type 'void'" felt less intuitive. In the end, I think our runtime error message will provide the best guidance with exact location.

  

• Updated the configuration reference documentation which was still not updated

• Documented Astro.locals.starlightRoute.sidebar in the route data reference page. Right now, I just started by inlining everything in details as a base and we can later restructure/shorten/move it if needed.

• Did some refactor in utils/navigation.ts as pointed out in this comment. I also found some old data that we were still passing around from before sidebar intermediate representations, so I cleaned those up as well.

I also played a bit with the idea of allowing either directory: '.' or directory: '' in the config (not included). After implementing a basic version and actually trying out the directory: '.' option by typing it in my Astro config, I found it more confusing than just using directory: '':

• . usually refers to the current directory, so while editing the config, my current directory was the project root but the directory we would be autogenerating from is the src/conten/docs/ directory.
• If . is supported, can I use ..?

Only my opinion of course, and happy to discuss further, but I kept directory: '' for now since it felt more intuitive to me.

[delucis]

Beautiful work as always @HiDeoo!

I agree that '' for the root directory option works. It feels natural to go from 'dir/sub-dir' => 'dir' => '' and, like you say, this avoids the hint of the relative path syntax meaning current directory and suggesting '..' or './dir' might work.

Left a few comments — mostly pretty minor, although the collapsed question might warrant some discussion?

[delucis]

Perfect! Seems like a good cleanup indeed.

I think this is looking ready for release! Awesome work figuring out this new approach to make things more flexible for users @HiDeoo 👏

[HiDeoo]

Thanks for the thorough review and super helpful suggestions as always 🙌