Make it easier to add sidebar entries dynamically

[rzane]

What version of starlight are you using?

0.36.0

What is your idea?

The sidebar property in astro.config.ts allows you to specify sidebar entries, but doesn't allow you to reference collections.

After struggling to find a solution to this problem, I eventually read the source code for the sidebar component and realized I could manipulate the locals in a middleware to add entries to the sidebar.

However, this becomes relatively complicated since:

1. I'm now responsible for computing isCurrent
2. The pagination links are a function of the sidebar, and they were generated prior to middleware execution, and the function that computes them is not exported, I am forced to manually reimplement this logic.
3. The types for SidebarEntry, SidebarLink, and SidebarGroup are not exported. There's a workaround, but it is a minor inconvenience (see Re-export SidebarLink, SidebarGroup, and SidebarEntry types for consumer use #3411).

Points 1 and 2 could be solved by either exporting functions to recompute that data after changing the sidebar, or applying those changes in a middleware that runs after user defined middleware.

Why is this feature necessary?

Since the framework revolves around collections, it's really unintuitive that I can't easily incorporate them into my sidebar.

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]

Hi @rzane 👋

The sidebar property in astro.config.ts allows you to specify sidebar entries, but doesn't allow you to reference collections.

Could you clarify the use case here a bit? What are the collections you’re looking to reference? Are these Astro content collections other than docs? Or some other thing?

[samandmoore]

yes! that's exactly right. it's custom content collections.

[delucis]

Got it — thanks. Not a use case we’d considered previously. One thing you can do as a hack right now is to load files using Node’s filesystem APIs in the config, but it’s definitely more code than would be ideal.

That said, it’s a bit tricky to design a generic solution on our end as other collections don’t provide guarantees about what frontmatter they have and we also don’t know how you’re setting up routing for them. For example, you could have src/content/other-collection/example/one.md, but we don’t know if that should be linked as /example/one or /somewhere-else/example/one etc. and we also don’t know if the other-collection entries have title, sidebar, etc. in their frontmatter.

What’s your use case for splitting things into additional collections? Are they also using Starlight’s schema? Or are they a different format/type of content?

[donmccurdy]

Unless I've missed another way to do it, I think I have the same need. My use case would be for documenting a software library, such that each public export gets its own page and an entry in the sidebar. I can process the codebase so that the 'types' for the library are in a single flat JSON file...

[
 {title: 'Gizmo', slug: 'classes/Gizmo', description: '', properties: [], methods: [], ...} 
 {title: 'Widget', slug: 'classes/Widget', description: '', properties: [], methods: [], ...} 
]

... but I'm not sure how to make these appear in the sidebar without creating explicit .md pages for each export, or hard-coding the exports in the sidebar. I tried doing something like this in astro.config.mjs...

const coreItems = JSON.parse(await readFile('./src/data/api.json', 'utf8'));

export default defineConfig({
	integrations: [
		starlight({
			title: 'My Docs',
			sidebar: [
				{
					label: 'API',
					items: coreItems.map((item) => ({
						label: item.title,
						slug: item.slug,
					})),
				},
			],
		}),
	],
});

...after defining a collection with the same JSON, but see The slug "classes/Gizmo" specified in the Starlight sidebar config does not exist.. The format/schema of the JSON is flexible; I assume I'll need to adapt it to Starlight anyway.

[delucis]

The slug property is for pages Starlight is responsible for creating (defined in the docs content collection), but if you already have these pages created some other way and just want to link them you can use the link property instead:

coreItems.map((item) => ({
	label: item.title,
	link: '/' + item.slug,
}))

[samandmoore]

I have been thinking about this a bit more today and I wanted to share...

The use-case that @rzane and I have is mostly that we want to be able to have a custom docs schema for subsets of the files in the docs directory. e.g. we have docs/rules/ and docs/blips/ and docs/guides/ each wanting slightly different frontmatter schemas with some required fields. So, if we had the ability to have custom schemas for certain globs in the docs/ directory then we'd likely not this for our main use-case.

To work around that, we have to move the docs out of docs/ and then add custom rendering logic which makes them incompatible with the default sidebar, etc.

It would still be a useful feature though.

[delucis]

To share a couple of approaches to what you’re describing:

• In Astro’s docs we extend Starlight’s schemas to define a union of different frontmatter shapes. Admittedly this does not enforce per-glob frontmatter, but does at least give us some control over valid shapes.

• It is possible to write a custom content collection loader to do what you describe while avoiding the custom rendering logic. Starlight’s default docsLoader() is a wrapper around Astro’s glob() loader. You could instead provide a custom loader that is able to glob multiple locations and validate each with its schema (extending Starlight’s default schema to ensure all the expected default values are present).

Might be nice to make this approach easier but want to at least share these pointers when I had a spare moment!

[samandmoore]

thanks for that intel. that's helpful and might allow us to clean up a few things in the short term.