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.

[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)