Closed lorenzolewis closed 1 year ago
Expanding onto this with https://github.com/withastro/starlight/issues/420, the order for deriving this could be:
title
(required)sidebar > label
(optional)...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.
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.
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.
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 thelabel
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 thetitle
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?
Participation