Deploying to a subpath (base configuration)

[mayank99]

What version of starlight are you using?

0.37.3

What is your idea?

It would be nice if Starlight had an easy, well-documented way to create a website that can be hosted on a subpath.

Astro has a base configuration but it does not seem to be enough on its own. For example, it will create the correct directory URL structure but it won't automatically prepend the base path to URLs in markdown. I'm correcting for this by writing a plugin, but this seems like something Starlight could potentially handle out-of-the-box.

Why is this feature necessary?

This feature would be useful for anyone who already has a website running on the top level (/) and wants to deploy their docs to a subpath (e.g. /docs).

It's unclear to me what is and isn't handled automatically (by Astro, by Starlight) when base is set. That's where clear documentation would be useful as well.

I created two Stackblitz examples to demonstrate the current reality:

• Vanilla Astro: stackblitz.com/edit/github-wcsfahor
• With Starlight: stackblitz.com/edit/github-rnzo2pup

In both examples, any markdown links are broken (they don't include the BASE_URL). Further inspection shows that Starlight does automatically handle base in some cases (e.g. in the sidebar links) but not for others (e.g. actions on the homepage don't include BASE_URL but only during dev).

Not sure if this is the best place to discuss this because I can't tell what is working-as-intended vs bug vs missing feature vs missing documentation.

Do you have examples of this feature in other projects?

React Router automatically handles links when basename is set, but it's not the same situation because they do have explicit APIs (e.g. <Link>, useHref()).

Participation

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

[delucis]

it will create the correct directory structure but it won't automatically prepend the base path to URLs in markdown

This is partially intentional, or at least, hard for us to definitively fix: while it’s true that a lot of links are usually internal, it’s also plausible for people to link “up” out of a base-prefixed site. For example, imagine a product that has a Starlight docs site deployed with base: "docs". It may include links to / or /pricing in the docs which are intended to link to the marketing site potentially. For those links, prefixing with /docs would break them.

Currently we handle base for links that Starlight is entirely responsible for like the sidebar where we know you’re linking to an internal page.

That said, it’s still worth discussing options as it’s a question we get regularly enough (here’s a similar issue: #932)

Maybe there’s a way to make this behaviour optional. A couple of things give me pause:

• we likely couldn’t guarantee adding base everywhere (Markdown links sure, actions too, but <a> inside a component somewhere? probably not)
• I’m not sure how someone would “opt out” of prefixing, which would make hitting that use case deeply painful, because you’d have to disable prefixing and then manually prefix all existing links

I did share an example plugin here a while back for Markdown links in case it helps: #1763 (reply in thread)

[mayank99]

Thanks for the useful links to other issues/discussions. I did do a search but it was difficult to find anything because "base" and "URL" are such broad terms.

That's a good point around keeping the ability to link to sibling sites that are hosted under the same domain. I do think it would be easy to work around (e.g. using HTML syntax inside Markdown), but explicit is perhaps less confusing?

For non markdown files (.astro, .jsx, etc), I agree it's not a good idea to handle it automatically. But these cases are not too annoying to deal with today, because it's easy to concatenate the href value with import.meta.env.BASE_URL (and even create helper components, similar to React Router's Link).

In any case, I think what's really essential is clear documentation and perhaps a working example.

[mayank99]

Continued from #3666:

I assumed this part to mean actions is good to change.

Markdown links sure, actions too, but inside a component somewhere? probably not

The problem right now is you can't access BASE_URL and do string concatenation in the frontmatter. Hardcoding results in two sources of truth, which is not nice.

The PR could be released in a minor version if breaking change is the only concern.

[HiDeoo]

The PR could be released in a minor version if breaking change is the only concern.

I think more than the breaking change aspect, the main concern is that this change may not be desired by all users and there would be no way to opt-out of it as mentioned in the discussion.

Maybe there’s a way to make this behaviour optional.

I think the plugin approach, that users can choose to install, that you initially mentioned could be a good idea for such cases. I am not a heavy user of base although for the few times I used it, I personally made a small plugin to handle:

• Markdown/MDX links
• All links in component props used in MDX files, e.g. like in <LinkCard> Starlight default components but also custom ones
• Actions, custom slugs, etc.

If there is any interest, I could clean it up a bit and publish it as a plugin at some point.

[mayank99]

After a lot of tinkering with the splash page, here's what I've found:

• If using index.mdx inside src/content/docs, the base is ignored by hero.actions. (what update hero actions to handle base prefix #3666 was trying to fix)
• If using index.astro inside src/pages (with the exact same frontmatter values passed to <StarlightPage>), the base works automatically.

(This is for the production build. There are some differences during development too)

I'm not sure if this should be considered a bug in Starlight, this unblocks me for now. Thanks for all your help.

A plugin would be useful, but a written guide in the Starlight docs would be also be useful, even if it simply points to a userland plugin (published or reference implementation).