Support relative paths in Starlight config (#318)

Co-authored-by: Bjorn Lu <bjorn@bjornlu.com>

5 files changed, 25 insertions, 18 deletions

diff --git a/.changeset/rotten-shoes-fix.md b/.changeset/rotten-shoes-fix.md
new file mode 100644
index 00000000..7a165bc7
--- /dev/null
+++ b/.changeset/rotten-shoes-fix.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": patch
+---
+
+Support relative paths in Starlight config for `customCSS` and `logo` paths
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 7b3a9854..752b28a9 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -18,8 +18,8 @@ export default defineConfig({
     starlight({
       title: 'Starlight',
       logo: {
-        light: '/src/assets/logo-light.svg',
-        dark: '/src/assets/logo-dark.svg',
+        light: './src/assets/logo-light.svg',
+        dark: './src/assets/logo-dark.svg',
         replacesTitle: true,
       },
       editLink: {
@@ -47,7 +47,7 @@ export default defineConfig({
           attrs: { property: 'twitter:image', content: site + 'og.jpg?v=1' },
         },
       ],
-      customCss: process.env.NO_GRADIENTS ? [] : ['/src/assets/landing.css'],
+      customCss: process.env.NO_GRADIENTS ? [] : ['./src/assets/landing.css'],
       locales,
       sidebar: [
         {
diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx
index 5b803859..c711c30c 100644
--- a/docs/src/content/docs/guides/customization.mdx
+++ b/docs/src/content/docs/guides/customization.mdx
@@ -37,7 +37,7 @@ Adding a custom logo to the site header is a quick way to add your individual br
        starlight({
          title: 'Docs With My Logo',
          logo: {
-           src: '/src/assets/my-logo.svg',
+           src: './src/assets/my-logo.svg',
          },
        }),
      ],
@@ -52,7 +52,7 @@ The `title` text will still be included for screen readers so that the header re
 starlight({
   title: 'Docs With My Logo',
   logo: {
-    src: '/src/assets/my-logo.svg',
+    src: './src/assets/my-logo.svg',
     replacesTitle: true,
   },
 }),
@@ -81,8 +81,8 @@ You can display different versions of your logo in light and dark modes.
    starlight({
      title: 'Docs With My Logo',
      logo: {
-       light: '/src/assets/light-logo.svg',
-       dark: '/src/assets/dark-logo.svg',
+       light: './src/assets/light-logo.svg',
+       dark: './src/assets/dark-logo.svg',
      },
    }),
    ```
@@ -293,8 +293,8 @@ Customize the styles applied to your Starlight site by providing additional CSS
        starlight({
          title: 'Docs With Custom CSS',
          customCss: [
-           // Path to your custom CSS file, starting with /
-           '/src/styles/custom.css',
+           // Relative path to your custom CSS file
+           './src/styles/custom.css',
          ],
        }),
      ],
@@ -356,8 +356,8 @@ To use Google Fonts, follow the [Fontsource set-up guide](#set-up-a-fontsource-f
        starlight({
          title: 'Docs With a Custom Typeface',
          customCss: [
-           // Path to your @font-face CSS file.
-           '/src/fonts/font-face.css',
+           // Relative path to your @font-face CSS file.
+           './src/fonts/font-face.css',
          ],
        }),
      ],
diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
index b71f9974..3ea91414 100644
--- a/docs/src/content/docs/reference/configuration.md
+++ b/docs/src/content/docs/reference/configuration.md
@@ -44,7 +44,7 @@ Set a logo image to show in the navigation bar alongside or instead of the site
 ```js
 starlight({
   logo: {
-    src: '/src/assets/my-logo.svg',
+    src: './src/assets/my-logo.svg',
   },
 });
 ```
@@ -318,11 +318,11 @@ starlight({
 
 Provide CSS files to customize the look and feel of your Starlight site.
 
-Supports local CSS files relative to the root of your project, e.g. `'/src/custom.css'`, and CSS you installed as an npm module, e.g. `'@fontsource/roboto'`.
+Supports local CSS files relative to the root of your project, e.g. `'./src/custom.css'`, and CSS you installed as an npm module, e.g. `'@fontsource/roboto'`.
 
 ```js
 starlight({
-  customCss: ['/src/custom-styles.css', '@fontsource/roboto'],
+  customCss: ['./src/custom-styles.css', '@fontsource/roboto'],
 });
 ```
 
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 5e4571be..bf97acb2 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -6,7 +6,7 @@ import type {
   ViteUserConfig,
 } from 'astro';
 import { spawn } from 'node:child_process';
-import { dirname, relative } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { starlightAsides } from './integrations/asides';
 import { starlightSitemap } from './integrations/sitemap';
@@ -88,18 +88,20 @@ function vitePluginStarlightUserConfig(
   opts: StarlightConfig,
   { root }: AstroConfig
 ): NonNullable<ViteUserConfig['plugins']>[number] {
+  const resolveRelativeId = (id: string) =>
+    id.startsWith('.') ? resolve(fileURLToPath(root), id) : id;
   const modules = {
     'virtual:starlight/user-config': `export default ${JSON.stringify(opts)}`,
     'virtual:starlight/project-context': `export default ${JSON.stringify({
       root,
     })}`,
     'virtual:starlight/user-css': opts.customCss
-      .map((id) => `import "${id}";`)
+      .map((id) => `import "${resolveRelativeId(id)}";`)
       .join(''),
     'virtual:starlight/user-images': opts.logo
       ? 'src' in opts.logo
-        ? `import src from "${opts.logo.src}"; export const logos = { dark: src, light: src };`
-        : `import dark from "${opts.logo.dark}"; import light from "${opts.logo.light}"; export const logos = { dark, light };`
+        ? `import src from "${resolveRelativeId(opts.logo.src)}"; export const logos = { dark: src, light: src };`
+        : `import dark from "${resolveRelativeId(opts.logo.dark)}"; import light from "${resolveRelativeId(opts.logo.light)}"; export const logos = { dark, light };`
       : 'export const logos = {};',
   };
   const resolutionMap = Object.fromEntries(