Best Practice: Starlight living as a proxied subdirectory

[brob]

I'll be moving a Starlight implementation from its own domain to be proxied under a main domain (from a Nextjs site).

I'm hoping to get some insight into best practice around links and image URLs and keeping them easy to maintain and run locally from the Starlight repository, but also have them work from the proxy.

The proxy is maindomain.com/docs/ -> Starlight

All links when run under the proxy need to be at /docs (images included), but when run as an individual starlight project, they need to be local to the Starlight implementation (as far as I can tell).

Would love any insights or best practices

[delucis]

Hi @brob — good question!

I think for a case like this I would recommend setting Astro’s base config option to the proxied path, so something like:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  base: '/docs/',
  integrations: [
    starlight({
      title: 'My delightful docs site',
    }),
  ],
});

This will apply in both cases, so when running the local project everything will also be prefixed with /docs/. I wasn’t clear from the description if that would be an issue. If it’s only for local development, I guess it wouldn’t be an issue if you need to navigate to /docs/ instead of / to see the site.

base will take care of changing how a bunch of stuff is referenced:

• All assets like JS, CSS etc. For example, a CSS file might be linked to as /docs/_astro/something.css
• Starlight’s sidebar will include the base for you in its links.

What Astro/Starlight don’t take care of automatically are links inside your content. For example, if you have some Markdown like this:

Check out [our deployment guide](/deploy/) for more details.

We can’t really safely assume you mean /docs/deploy/ — maybe you really do want to link out below the base? So in this set up, you do kind of ideally want to author those with the /docs/ prefix.

That said, given you’re moving an existing code base that could be a bit of a pain, so one option could be to add a small remark plugin which processes all links and injects the base automatically.

---

Edit: Ah, and one thing that sometimes trips people up: base does not create that directory in build output, i.e. index.html will still be built to dist/index.html not to dist/docs/index.html. This means we can support hosts like GitHub Pages that add that prefix automatically. So if that’s an issue, you can do stuff like also setting outDir to dist/docs/ in case you need that directory in the deployment.

[brob]

Thanks for all your help! I successfully have my Proof of Concept on this and hopefully (barring issues with SEO concerns), I'll be taking a site live later this year with this concept!

Do you think this is a common enough pattern that a blog post/video tutorial on doing it would be beneficial? I may make one

[delucis]

Definitely! Always love to see people explain how they tackled these more complex, but not so uncommon scenarios.

[brob]

Just for future folks here's my video on doing this: https://www.youtube.com/watch?v=12o7WxjAxjM

[HiDeoo]

Just watched the video, amazing work, so thorough while still being concise and easy to follow. Loved it, thanks a lot for sharing 🙌

[delucis]

Oh wow, yeah! Did a great job condensing my screed above into the simple minimal steps needed 💖