Make sidebar entry label optional in config

lorenzolewis commented 1 year ago

What version of `starlight` are you using?

0.5.5

What is your idea?

Since the title frontmatter is required in markdown, it could make sense to mark the label for sidebar items in the Starlight config optional. If left blank it could attempt to resolve against an entry for the respective link and render the title front matter for that entry. If it's not an entry (such as a external link) then it could just render the link itself.

Why is this feature necessary?

When doing a custom sidebar it can quickly become tedious to work with a lot of entries. This makes it to where you can rely on some of Starlight/Astro's build in power to fill in these values for you. Add on a layer of i18n and this can be an even more complicated sidebar config.

Do you have examples of this feature in other projects?

Docusaurus shorthand syntax (be sure to select the "Shorthand" tab): https://docusaurus.io/docs/sidebar/items#doc-shorthand

Participation

[x] I am willing to submit a pull request for this issue.

lorenzolewis commented 1 year ago

Expanding onto this with https://github.com/withastro/starlight/issues/420, the order for deriving this could be:

Doc frontmatter title (required)
Doc frontmatter sidebar > label (optional)
Starlight Config (only overrides the above if explicitly set)

...with the first being the least important and the last the most.

This could cause an odd DX behaviour where sidebar > label is set but then overridden by a respective entry in starlight config, though.

delucis commented 1 year ago

I think my preference is for the frontmatter sidebar values to currently apply only to autogenerated sidebars. As you mentioned in passing, if label is not required, you could end up with a situation where there isn’t really a good label available (e.g. for external links).

The solution would be to have a distinct item type for internal documents — which can then error if the linked page is not found. I have considered this, e.g.

sidebar: [
  // using `id` instead of `link` for internal links
  // label etc. is generated from frontmatter if not set
  { id: 'getting-started.md' },

  // or even, support a shorthand string syntax that does the same:
  'showcase.mdx',
],

There’s some added complexity here, and I don’t love the proliferation of config types that people then need to remember. It would have the added advantage of making it impossible to have a broken internal link in the sidebar if you follow this model.

That said, I think I’d like to build out some other complex parts of the Starlight featureset first before thinking about this. In particular, if we’ll allow injecting pages via a plugin interface, I’d want to make sure this was compatible with that.

Hope it’s OK if I close as “Not yet” and hopefully can be revisited one day.

lorenzolewis commented 1 year ago

Makes sense. I think there's value from an i18n perspective so that you can centrally define the "shape" of the sidebar in the config while leaving the exact labelling in the front matter (without having to add a lot of sidebar.hidden and sidebar.order properties. But the solution you talked about for "someday" sounds perfect.

withastro / starlight