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.

[DarthGigi]

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