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,
}))