Groupless autogenarated sidebar links

[HiDeoo]

What version of starlight are you using?

0.35.1

What is your idea?

This proposal suggests a new alternative to define autogenerated sidebar links that are not relying on sidebar groups to allow for a more flexible usage of autogenerated links in sidebars.

It builds on the existing autogenerated sidebar groups feature by allowing the omission of the label property.

interface Autogenerated {
-  label: string;
+  label?: string;
   autogenerate: {
     directory: string;
   };
}

When the label property is omitted, the autogenerated links will no longer be grouped, resulting in a list of links that are not nested under a group label.

• If a group label is specified, a group is created to contain the autogenerated links.
• If the label is omitted, a group is not created.

Why is this feature necessary?

Here are some use cases that I've encountered where the current autogenerated sidebar groups are not flexible enough.

Single non-root autogenerated sidebar group

Considering the following file structure:

src/
└── content/
    └── docs/
        └── constellations/
            ├── andromeda.md
            ├── carina.md
            └── centaurus.md

The desired outcome is to have a sidebar that automatically generates links for each file in the constellations/ directory:

Andromeda
Carina
Centaurus

When using the current autogenerated sidebar groups feature, you would typically define a sidebar group like this:

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Autogenerate a group of links for the 'constellations' directory.
      autogenerate: { directory: 'constellations' },
    },
  ],
});

This results in the following sidebar structure with an extra group that is not desired:

Constellations
├── Andromeda
├── Carina
└── Centaurus

Proposal config to achieve the desired outcome

starlight({
  sidebar: [
    {
      // Omit the label to create a list of autogenerated links without a group.
      // Autogenerate a group of links for the 'constellations' directory.
      autogenerate: { directory: 'constellations' },
    },
  ],
});

Mixed autogenerated and manual sidebar links

Considering the following file structure:

src/
└── content/
    └── docs/
        └── constellations/
            ├── andromeda.md
            ├── carina.md
            └── centaurus.md

The desired outcome is to have an autogenerated sidebar group for the constellations/ directory with an additional first link which would redirect to the NASA website:

Constellations
├── NASA (external link)
├── Andromeda
├── Carina
└── Centaurus

When using the current autogenerated sidebar groups feature, it's not possible to also to add items like you would in a regular sidebar group, e.g. the following configuration is invalid:

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Autogenerate a group of links for the 'constellations' directory.
      autogenerate: { directory: 'constellations' },
      items: [
        // An external link to the NASA website.
        { label: 'NASA', link: 'https://www.nasa.gov/' },
      ],
    },
  ],
});

Proposal config to achieve the desired outcome

starlight({
  sidebar: [
    // A group labelled "Constellations".
    {
      label: 'Constellations',
      items: [
        // An external link to the NASA website.
        { label: 'NASA', link: 'https://www.nasa.gov/' },
        {
          // Omit the label to create a list of autogenerated links without a group.
          // Autogenerate a group of links for the 'constellations' directory.
          autogenerate: { directory: 'constellations' },
        },
      ],
    },
  ],
});

Do you have examples of this feature in other projects?

• In Docusaurus, autogenerated sidebar items are slices by default (which are a bit similar to the proposed feature) and if you want to group them, you use a regular group and use the slice as any other item in the group.
  • I think this may be a better approach although it would require a breaking change in Starlight or lead to confusion if co-existing with the existing autogenerated sidebar groups.

Other alternatives considered

1. Adding a new property to the autogenerate object, e.g. grouped: false, or spread: true, to indicate that the links should not be grouped. This approach would be less intuitive as you would still need to define a group label even though it would not be used.
2. Adding an entirely new type of allowed item in the sidebar, e.g. { type: autogenerate, directory: "api" }, which is similar to the slice type in Docusaurus. Considering Starlight already has autogenerated sidebar groups, this could lead to confusion between the two types.

Participation

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

[james-camilleri]

I was just trying to figure out how to configure Starlight to do something like this and it turns out it's not possible. This feature would definitely be handy for adding additional menu items or groups to the default autogenerated sidebar. As things stand, to the best of my knowledge, as soon as you need to add custom menu items the default autogenerated tree has to be packed into a subfolder/group on the sidebar.

[delucis]

In Docusaurus, autogenerated sidebar items are slices by default (which are a bit similar to the proposed feature) and if you want to group them, you use a regular group and use the slice as any other item in the group.

• I think this may be a better approach although it would require a breaking change in Starlight or lead to confusion if co-existing with the existing autogenerated sidebar groups.

So this would look something like this?

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

vs the current syntax:

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

You like that approach because it means the autogenerate “slice” would always be used the same way? I guess it’s true that it also sets you up for easily adding items to the group without needing to switch the syntax.

Could be worth considering whether it’s a worthwhile breaking change to make pre-v1.

[HiDeoo]

You like that approach because it means the autogenerate “slice” would always be used the same way? I guess it’s true that it also sets you up for easily adding items to the group without needing to switch the syntax.

Yeah, it's mostly about the group syntax always being at least { label: string, items: [] } that my mind find easier to work with (and I think even documenting may be easier, you just document group once (vs groups and autogenerated groups), and everything else is something you throw in the items array).

Could be worth considering whether it’s a worthwhile breaking change to make pre-v1.

I'm not sure if it's an obvious worthwhile change, and I was hoping this discussion could help on that.

I also considered the idea of supporting both syntaxes for a while and then deprecating the old one, but I was a bit afraid on how TS would handle this (as we've seen in https://github.com/withastro/starlight/pull/3266/files#diff-7a2ea84cfc73ff1bbc2d80acbd05c63e84bc9e0bdf98d8dfb1203f242a8f2627 it's already not properly handling our non-discriminated union without manual help) altho I could definitely explore it a bit in the surface to at least see how it would look like in practice.

[delucis]

If we do break it, it would at least be one that is easy to provide clear error messages and guidance on: whenever encountering label and autogenerate together, we can log an error explaining the migration path and even showing the exact change needed, e.g.

Found an `autogenerate` object with a `label`. Support for setting `label` on autogenerated sidebar configuration objects was removed in Starlight v0.X.0.

Please wrap your autogenerate configuration object in an `items` array instead:

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

[HiDeoo]

Yeah, Ive been playing a bit with it locally and even the refactor is relatively easy and quick to do. It's also still compatible with some other improvements I'm planning on proposing later.

I'll continue toying around with it a bit more but doesn't feel "that bad" of a breaking change.

[delucis]

On the whole my gut feeling is positive that we avoid two ways to group links, but I think you playing around and then seeing maybe how the documentation feels to write will be helpful pointers.

[HiDeoo]

One thing I noticed while playing around with all the suggested approaches so far is how less convenient this can become for plugins that try to customize auto-generated links and groups, e.g. starlight-auto-sidebar.

Right now, it's really easy to map an autogenerated group defined in the Starlight sidebar configuration to the actual links and groups that have been generated from tha configuration as the entire content is located in a group with a known name. With the new approaches, this become a bit more tricky. It's still possible to write some algorithms that can do such mapping between the config and the actual sidebar content, but it becomes more complex and they may exist some cases where it becomes very tricky depending on the configuration.

I think my next step would be to try to refactor a plugin like starlight-auto-sidebar to support a similar approach and explore a few ideas I have in mind to make it easier for plugins to customize auto-generated links and groups. An obvious one could just be to indicate in route data if a link or group has been auto-generated (that would be data unused by Starlight itself, but could be useful for plugins) but I have some other ideas as well.

[alvinometric]

I want this too!

[kevinzunigacuellar]

I like the combination of both (the items array and a new type property). So it will look something like this:

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

[delucis]

Would other entry types also need type: 'group', type: 'link' etc.? That could be a bit verbose I guess. But also weird if there's only one valid type.

[kevinzunigacuellar]

Good point! I wouldn't want it to be more verbose. Perhaps this is a better fit? (Just brainstorming breaking APIs at this point 😆 ...)

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

[InertSloth]

I came here at @HiDeoo's mention, My use case was using the wonderful https://starlight-sidebar-topics.netlify.app/ to display a topic list to pick from ala the Astro official docs, and I didn't want to repeat the group when displaying the items in a topic. I could do it using a manual items array but not with autogenerate. This feature would solve my use case as well.