How to serve Starlight from nested public path (subpath, subdirectory)

[stereobooster]

What version of starlight are you using?

0.25.0

What is your idea?

Be able to server starlight from subpath. To be precise be able to put all Starlight code in subpath:

www
   some-folder
      starlight code here
   other-folder
      other code here

Workaround discussed here #966 doesn't work for this case. Because generated files use root path <script type="module" src="/_astro/page.LS5KDvwX.js">.

Why is this feature necessary?

In my case we have a lot of different documentation served from the same domain, but from different subpaths. Each documentation website owned by different teams and may use different documentation generators

Other use case is github.io deployments, like https://jackyzha0.github.io/quartz

Do you have examples of this feature in other projects?

• mdBook site-url = "/example-book/"
• quartz baseUrl: "jackyzha0.github.io/quartz"
• vitejs

Participation

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

[stereobooster]

This doesn't have any effect

export default defineConfig({
  site: "https://example.com/some/thing",
  integrations: [starlight({})],
  vite: {
    base: "/some/thing",
  }
});

[delucis]

This is possible using Astro’s base configuration option instead of the Vite option (which I think has no effect in Astro projects):

export default defineConfig({
  site: "https://example.com/",
  base: "some/thing",
  integrations: [starlight({})],
});

The Astro guide to deploying to GitHub Pages might also be useful.

[stereobooster]

Thank you. There is still problem that I need to prefix every link with some/thing e.g.

[page](/some/thing/page) instead of [page](/page)

I know it can be solved with remark/rehype plugin, but a bit of drawback

Here is rehype plugin, if anybody needs it

import { visit } from "unist-util-visit";

export const rehypeLinks = (options) => {
  let base = options?.base;

  return (ast, file) => {
    if (typeof base !== "string") return;
    if (!base.startsWith("/")) base = "/" + base;
    if (base.length > 1 && base[base.length - 1] === "/")
      base = base.slice(0, -1);

    visit(ast, "element", function (node, index, parent) {
      if (node.tagName === "a") {
        const href = node.properties.href;
        if (
          typeof href === "string" &&
          href.startsWith("/") &&
          !href.startsWith(base)
        ) {
          node.properties.href = base + href;
        }
      }
    });
  };
};

const base = "some/thing";

export default defineConfig({
  base,
  integrations: [starlight({})],
  markdown: {
    rehypePlugins: [[rehypeLinks, { base }]],
  },
});

[delucis]

Thanks for sharing that solution!

Yes, that's always a bit awkward, but not something we can really take an opinion on because it's hard to know if when a user links /something if they mean that relative to base or relative to the server root — in theory either are possible, but if we automatically prefixed links we'd block people from linking out to a different subdirectory.

Glad you could get it working 🙌