I am using custom pages in Starlight to take advantage of Astro's Dynamic Routes for generating pages from a JSON file. How can I get the Starlight sidebar to show links to the generated pages?
#Sidebar generation for custom pages in Starlight
broken badge
covert ivyBOT
Hi @broken badge. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
If you are generating custom pages in Starlight using Astro’s dynamic routes (e.g., from a JSON file), these pages are typically created in the src/pages/ directory. According to the Starlight documentation, pages created this way are not part of the Starlight content collection (src/content/docs/) and therefore cannot be included in autogenerated sidebar groups or benefit from sidebar customization via frontmatter. The sidebar frontmatter property for customizing how the page appears in autogenerated link groups is not available for custom pages created with the <StarlightPage /> component, and such pages cannot be added to an autogenerated sidebar group Using Starlight’s design in custom pages.
However, you can manually add links to your custom pages in the global sidebar configuration. In your astro.config.mjs, you can define sidebar entries that point to your custom routes, just as you would for any external or non-docs page:
starlight({
sidebar: [
{ label: 'Home', link: '/' },
{
label: 'Dynamic Pages',
items: [
{ label: 'Page 1', link: '/dynamic/page-1/' },
{ label: 'Page 2', link: '/dynamic/page-2/' },
// Add more links as needed
],
},
],
});
If your dynamic routes are known at build time (e.g., you can enumerate them from your JSON), you can generate this sidebar configuration programmatically in your astro.config.mjs before passing it to Starlight Sidebar configuration reference.
Summary:
- Custom pages in
src/pages/cannot be included in autogenerated sidebar groups. - You must manually add links to these pages in your sidebar configuration.
- Programmatic generation of the sidebar config is possible if you know your dynamic routes at build time.
There is no built-in way in Starlight to automatically include dynamically generated custom pages in the sidebar; manual configuration is required.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
broken badge
@covert ivy The JSON source file will be used to generate potentially a few hundred pages as part of a software library's reference documentation. It is not feasible to also have to manually maintain a list of the generated pages for the sidebar config, mostly as the content of the JSON will change over time, as well as being quite the overhead. Is there a way I can use the same JSON source to provide the sidebar config? This is all SSG.
covert ivyBOT
Let me check the knowledge base for you again. One moment! :books:
I'm sorry, but the knowledge sources do not describe a built-in way in Starlight to programmatically generate the sidebar configuration from an external JSON source at build time. The documentation explains that:
- Autogenerated sidebar groups are only available for content in the
src/content/docs/directory, not for custom pages generated via dynamic routes insrc/pages/Using Starlight’s design in custom pages. - The sidebar configuration in
astro.config.mjscan be set manually, and you can add links to any route, but there is no mention of a mechanism to automatically sync this with an external data source like a JSON file Sidebar configuration reference.
While the documentation shows that you can configure the sidebar with arrays and objects, and even generate it programmatically within your config file, it does not provide an example or explicit support for using the same JSON source for both page generation and sidebar configuration. Therefore, you would need to implement your own logic in your config file to read the JSON and generate the sidebar array, but this is not covered or officially supported in the documentation.