Improved support for serving Starlight docs from a custom subpath

[mirrorleap]

What version of starlight are you using?

0.5.2

What is your idea?

Starlight integration helps to easily build documentation with Astro. However, by default, it converts the entire Astro site into a documentation site. It will be a useful feature if Starlight docs can be served from a custom path.

Why is this feature necessary?

Astro has a unique feature that allows for multiple integrations including UI frameworks and other functionality. Starlight is one of those exciting integrations.

Allowing Starlight docs to be served from a sub/custom path, will have the following benefits:

• 1 project for both main and documentation site
• Quicker deployment and maintenance
• Easier integrations with other Astro functionality

Do you have examples of this feature in other projects?

Example -

Route(s) for Astro site content:

• /
• /about
• /blog

Route(s) For Starlight docs within Astro site:

• /docs
• /docs/overview
• /docs/integrations

Participation

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

[BryceRussell]

For a quick and hacky solution you can nest the docs collection within a second docs folder like src/content/docs/docs to prefix all starlight paths with /docs

[mirrorleap]

Thanks for the quick solution. Seems to work alright, although I can't find a way to update the nav link in the header. It still points to the root url.

[BryceRussell]

Unfortunately configuring the href of the site title is not currently possible but you can use a client side script to correct the href when the page loads, something like this:

starlight({
  head: [
    {
      tag: 'script',
      content: `window.addEventListener('load', () => document.querySelector('.site-title').href += 'docs/')`,
    },
  ],
});

[mirrorleap]

Thanks for the workaround.

[delucis]

Thanks for the issue @mirrorleap! As @BryceRussell said, this workaround is available today and I just wrote some docs for this approach, but we would like to improve support here in the future.

I think most likely would be something like a base option:

// astro.config.mjs

defineConfig({
  integrations: [
    starlight({
      title: 'Docs at a subpath',
      base: 'guides',
    }),
  ],
});

This would prefix all Starlight routes with /guides/, so that e.g. src/content/docs/index.md is available at /guides/ instead of /.

There are some questions around this still to answer:

• Should Starlight’s 404 page also inject at /guides/404? This wouldn’t be picked up by most static hosts, but may be what’s expected when doing this as you presumably have other routes.

• What should happen to the Starlight site title link? As you noted, it currently will link to / (or /lang/ potentially for multilingual sites). I can imagine people wanting both / or /${base}/ in this case depending on their preference so may need to make this configurable. (As an example, https://terrateam.io/ includes Starlight on /docs and linking back to the home page feels right there.)

[jagu-sayan]

It's a must have for me :)
Like it's done by QuestDB website build with Docusauru (Look code).

Suggestion to add more powerful customization:

• possibility to customize header and footer section of Starlight
• possibility to use the same layout for all the website (main, blog and documentation)
• possibility to implement our own layout with an option useCustomLayout: true
• export components (like Search.astro, SiteTitle.astro, ...) used by header and footer to use them in our custom layout

[delucis]

Hey @jagu-sayan! As noted above this is already supported, we’d just like to improve the DX around it.

Thanks for sharing your other ideas — things in this direction are all stuff on our radar 🙌

[mirrorleap]

Hi @delucis, thanks for your response. I agree with your approach to have the base option.

// astro.config.mjs

defineConfig({
  integrations: [
    starlight({
      title: 'Docs at a subpath',
      base: 'guides',
    }),
  ],
});

Here are my suggestions:

• By default, Starlight's site-title link should point to /${base}/ but make it configurable. So, if someone wants the docs link to point to / or /random-link they are free to do so. In that case, the config would look like this:

// astro.config.mjs

defineConfig({
  integrations: [
    starlight({
      title: 'Docs at a subpath',
      title-link: '/'
      base: 'guides',
    }),
  ],
});

• Regarding the 404 (not found) page, it seems weird to have the docs at /guides but render this page at /404. Mainly because of the Starlight's styling/layout, and also because of main Astro site's 404 page. To me /guides/404 seems a more suitable option, however I don't fully understand why this wouldn't be picked up by static hosts.

[delucis]

I don't fully understand why this wouldn't be picked up by static hosts.

Hosts like Netlify, Vercel, and GitHub Pages have a very simple default behaviour where they look for a 404.html file in the root of the pages to deploy and serve it as the 404 page for any route they don’t find. That means they ignore any 404 files nested in a subdirectory. This is configurable — for example in the Starlight docs we tell Netlify to use /es/404 for 404s starting with /es/, /fr/404/ for 404s starting with /fr/ etc. — but would require some user config.

That said, if a user’s project already creates a root-level 404, then Starlight’s shouldn’t overwrite it.

[delucis]

Making a note that it might not be super clear what happens to base and language tags in URLs.

Which of these should the pattern be?

• /lang/base/ (e.g. /fr/docs/)
• /base/lang/ (e.g. /docs/fr/)

Usually language tags are the first segment in a URL path, but not sure if that’s what everyone looking for base support expects or not.

This wouldn’t impact base usage for monolingual sites though.

[spaceemotion]

Just came across an issue with starlight being incompatible with a custom 404 page. A base URL option would be great as I don't want to expose the documentation whenever a user enters a wrong URL in general.

[connor-baer]

v0.17.0 added the disable404Route config option to disable the injection of Astro’s default 404 route.

[guidiego]

@delucis as we have discussed in Discord, would like to get this issue! I have a branch as you can see in the historic of the issue. I figured out how to add baseUrl at the configs, but not the right entry point to make it work!

[itsmatteomanf]

I'd personally put the language before the base path, but imho it should be a selectable option.

If you have a monolingual site, with multi-lingual docs, then after the base path makes sense, if everything is multilingual having the language path moved in the middle of the path makes no sense.

[Genteure]

If there's multiple starlight sites in the same origin, should theme selection also be separated?

Currently starlight is using hardcoded starlight-theme:

starlight/packages/starlight/components/ThemeSelect.astro

Line 34 in 7d7f5cb

#key = 'starlight-theme';

starlight/packages/starlight/components/ThemeProvider.astro

Line 10 in 7d7f5cb

typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');

Example of separated theme selection implemented in mkdocs-material, they are prepending the base path to the key.

Excerpt of formatted source of https://squidfunk.github.io/mkdocs-material/:

__md_scope=new URL(".",location)
__md_get=(e, _=localStorage, t=__md_scope) => JSON.parse(_.getItem(t.pathname+"."+e))

Excerpt of formatted source of https://squidfunk.github.io/mkdocs-material/getting-started/:

__md_scope=new URL("..",location)

Excerpt of formatted source of https://squidfunk.github.io/mkdocs-material/blog/2023/10/02/sunsetting-gitter-towards-efficient-community-engagement/:

__md_scope=new URL("../../../../..",location)

[AutonomousCat]

+1

[JuanDa237]

+1

[kaytwo]

It appears that the below code:

starlight/packages/starlight/utils/createPathFormatter.ts

Line 36 in ec4b851

function formatPath(

was added after most of the conversation in this thread, which takes into consideration the base configuration when doing things like creating sidebars. At this point would it just be a matter of including these link formatters in the Starlight components, which would enable Starlight to respect the base config?

[delucis]

Starlight does respect Astro’s base config, but that is slightly different from what this discussion is about which is about a subpath within your Astro project.

For example, you could use base: '/apollo-mission/' in your Astro config to serve your entire Astro site from https://example.com/apollo-mission/.

But the case discussed above is for example you have an Astro site at / and want pages for Starlight at e.g. /docs/. This is supported today (see the “Use Starlight at a subpath” docs), but there’s some discussion around improvements.

[kaytwo]

Thanks - I'm running into the issue of using absolute paths to link within the Starlight project.
So my issue is that if I've got an <a href="/about">about</a> link, with base: '/apollo-mission/' the link will go to /about instead of /apollo-mission/about.

I think this might be a problem with Astro moreso than Starlight, but even so, adding a named export to the project that allows import {formatPath} from "@astrojs/starlight", could solve the problem with: <a href={formatPath('/about')}>about</a> without a bunch of other gymnastics. Honestly, this should probably be provided by the main astro package, but I don't see any analogous code in the main repo.

Minimum example: https://stackblitz.com/edit/github-mfobspu9?file=src%2Fpages%2Findex.astro

[delucis]

if I've got an <a href="/about">about</a> link, with base: '/apollo-mission/' the link will go to /about instead of /apollo-mission/about

Ah yeah, that is expected. Astro takes care of prefixing links it is responsible for (e.g. JS, CSS, optimized images etc.) and similarly Starlight will do so for links it is responsible for (e.g. in the sidebar, search results, etc.). But authored links like this are user responsibility as we can’t know if e.g. <a href="/"> intends to point at your base, or perhaps actually at the root of the domain. An Astro utility for link formatting could indeed be handy.

If you just need to prefix your site’s base, writing a utility for this is pretty simple though:

// src/utils/links.ts

/** The site’s `base` URL with any trailing slash removed. */
const base = import.meta.env.BASE_URL.replace(/\/$/, '');

/** Prefix a local link with the currently configured `base` URL. */
export function withBase(href: string): string {
  return base + href;
}

You could then use that when building links:

---
import { withBase } from '../utils/links';
---

<a href={withBase('/about')}>About</a>

[sarendipitee]

Hello from 2025 for people from google.

Current version of Starlight throws errors in util/navigation.ts about "cannot access property "hidden" if locales are not properly configured and it can be tricky to get the directory structure right.

You need this config (pieced together from several doc and discussion pages):

export default defineConfig({

	integrations: [
		starlight({
			title: 'Docs',
			defaultLocale: 'en',
			locales: {
				root: {
					label: 'English',
					lang: 'en',
				},
				en: {
					label: 'English',
				},
			},
		}),
	],
})

And this directory structure:

src/content/docs
└── docs        <--- Nested Sub path
    ├── index.md
    ├── overview.md
    ├── someotherpage.md
    ├── subfoldeder
    │   ├── examples.md

However what I still haven't figured out is how to avoid "docs" being treated as a root entry folder in the navigation,.

I tried both a custom id generator to replace out the sub paths

const docs = defineCollection({
	loader: docsLoader({
		generateId: ({entry, base, data}) => {
			if (entry == 'docs') {
				return entry
			}
			return entry.replace(/^(?:docs\/)*(.+)(?:\.(?:mdx*)])*$/, '$1')
		},
	}),
	schema: docsSchema(),
}

Which just breaks everything.

And changing the id slug via a route middleware just breaks the sub path:

import {defineRouteMiddleware} from '@astrojs/starlight/route-data'

export const onRequest = defineRouteMiddleware(context => {
	// Get the content collection entry for this page.
	const {entry} = context.locals.starlightRoute
	// Update the title to add an exclamation mark.
	entry.id = entry.id.replace(/^docs\//, '')
})

Finally, there doesn't seem to be a way to hide that specific group via frontmatter configuration.

So if that's a deal breaker / headache for you, either use a subdomain and a separate Astrojs project or use something else entirely.