Autogenerate label for sidebar links

[apfelbox]

What version of starlight are you using?

0.21.1

What is your idea?

Right now, due to the inability to customize folder/group labels and sorting, you need to build your sidebar manually in a large part.

It is annoying to also need to duplicate the page label: the page already has a title but the link in the sidebar needs a label as well.

Would be great, if

{ link: "some/page" }

would be allowed and it would automatically fetch the title of the page as label by default.

Why is this feature necessary?

Building larger sidebars is pretty fragile right now, as you need to duplicate a lot of things: all the links and the titles as well. This can get messed up pretty quickly.

Do you have examples of this feature in other projects?

No response

Participation

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

[delucis]

Thank you for the suggest @apfelbox! I’ve actually been meaning to propose something like this for a while. I’d probably suggest a new entry shape for this instead of the current link because link can also point to external content or pages Starlight is not aware of. So maybe something like id:

starlight({
  sidebar: [
    { id: 'guides/css-and-tailwind' },
    { label: 'Astro', link: 'https://astro.build/' },
  ],
})

That would then indicate to Starlight that the id is a content entry. It would also come with benefits like being able to error if you have a typo to avoid broken links.

We could still allow overriding the label if people needed that, but would infer label from the page frontmatter by default.

One step further would be to even support a shorthand for this form so you could provide just the id as a string:

starlight({
  sidebar: [
    'guides/css-and-tailwind',
    { label: 'Astro', link: 'https://astro.build/' },
  ],
})

That might help people who like the autogenerated sidebar but want easier control over ordering, or want to combine entries with external links etc. It reduces the boilerplate needed to move from autogeneration to listing the entries.

[lorenzolewis]

Personally I would use slug because in the Content Collection API an entry’s id contains the extension, whereas this does not (and imo should not).

[apfelbox]

I really like your proposal! 🙌💯

[lorenzolewis]

@delucis the behaviour you mention above with label, could that also be replicated for badge? If no badge property is specified in the config, then infer from the frontmatter. Since badge is optional, extending the type in the config to include false (i.e. badge: false) could be a way to allow users to ignore a badge in the front matter if needed. Similar idea with attrs as well.

[delucis]

Definitely — I’d assume it would behave 1:1 with how autogenerated links work, i.e. infer everything from frontmatter, with in this case the option to override if needed.

[lorenzolewis]

Having this would be so much better especially for i18n. The titles needing to be specified in the config AND the front matter for EACH locale is awkward. And translators often get confused why it isn’t updated correctly when they translate a page since they are focused on content and not code (I.e. the config)

[delucis]

Yes, agreed — I’ve also seen this with the Starlight docs.

[HiDeoo]

Since Starlight v0.25.0, the new syntax for specifying sidebar link items for internal links is available. You can read more about it in the "Internal links" section of the Sidebar Navigation guide.