Docs Multi-instance Support

[DarthGigi]

What version of starlight are you using?

0.7.3

What is your idea?

Basically the same thing as https://docusaurus.io/docs/docs-multi-instance. Being able to have multiple docs. For example, you can have documentation for Project X and Project Y separately.

Why is this feature necessary?

It can solve the issue where someone needs to have multiple documentations on a single website, so they don't have to create a new website for each.

Do you have examples of this feature in other projects?

• https://docs.dyte.io/
• https://wiki.iota.org/

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thanks for the issue @DarthGigi!

I think this could be something good to tackle alongside #347 — making the collection and base path configurable, would let multiple instances of Starlight own separate subpaths of a site.

[ringods]

I'm also interested to have this. I want to document multiple distinct "projects" on my personal site, each on a different path, each having a separate ToC, but adding up to a single shared site search index.

E.g.:

• /site/... (docs describing my own website setup)
• /homelab/... (docs describing my homelab)
• /sports/... (docs describing my cycling gear, associated electronics and configuration)

https://discord.com/channels/830184174198718474/1070481941863878697/1200532286978936832

[delucis]

Thanks for adding this feedback about a use case!

What is possible today would be to have those routes all as subdirectories under src/content/docs/, i.e. a file structure like:

src/
└── content/
    └── docs/
        ├── index.md     # a general hub if needed to link to the different sections
        ├── homelab/
        │   └── index.md
        ├── site/
        │   ├── index.md
        │   └── setup.md
        └── sports/
            ├── index.md
            └── bikes.md

The piece that is missing is built-in support for different navigation for each section. Although this is possible if you’re happy to do a bit of hacking and override the <Sidebar> component.

For example, with a simple sidebar config like:

// Partial astro.config.mjs

starlight({
  sidebar: [
    {
      label: 'Homelab',
      autogenerate: { directory: 'homelab' },
    },
    {
      label: 'Site Notes',
      autogenerate: { directory: 'site' },
    },
    {
      label: 'Sports',
      autogenerate: { directory: 'sports' },
    },
  ],
});

You could then override Sidebar and filter out the groups you don’t want:

---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/Sidebar.astro';

// Get the first part of the file path, i.e. "site/setup" would return "site"
const firstPathSegment = Astro.props.slug.split('/')[0];
// Filter out groups that don’t include links to the current sub directory
Astro.props.sidebar = Astro.props.sidebar.filter(
	(group) =>
		group.type === 'group' &&
		group.entries.some(
			(entry) => entry.type === 'link' && entry.href.startsWith('/' + firstPathSegment)
		)
);
---

<Default {...Astro.props}><slot /></Default>

[ringods]

@delucis would all of docs be a single content collection, or do I split this up in 3 content collections?

[delucis]

Yes in this example docs is a single content collection. Starlight only knows about docs currently and there’s no way to get it to look for files anywhere else.

[WhyFenceCode]

I used this but all i get is a blank side bar. Does this still work in the newest version, and if, is there anything else i need in that sidebar file.

[ringods]

@delucis could multi-instance be supported via the new content collections loader in the upcoming Astro 5.0 release?

https://docs.astro.build/en/guides/content-collections/#defining-the-collection-loader

[DarthGigi]

Hello, it's been a few months and I was wondering what the status of this feature is?

[LLIETAER]

Hello, I am also wondering is there something planned for this feature ?

[delucis]

Nothing planned currently. Astro is currently working on some new features in how content collections work. Probably won’t tackle this until after that given the overlap.

In the meantime, using the single docs/ directory but customising the sidebar to control what links are displayed is probably the best approach (or using separate projects if preferred).

The multi-sidebar plugin in the starlight-utils package might also come in handy — https://starlight-utils.pages.dev/utilities/multi-sidebar/ — and there’s a manual example of multiple sidebars available here: https://starlight-examples.netlify.app/examples/multi-sidebar/