customCSS error message

[Its-Just-Nans]

What version of starlight are you using?

5.15.8

What is your idea?

When we add a public css url in customCSS, the error message is imperfect.

8:31:15 [types] Generated 792ms
08:31:15 [vite] Re-optimizing dependencies because vite config has changed
08:31:15 [ERROR] Cannot import non-asset file /downloaded/katex.min.css which is inside /public. JS/CSS files inside /public are copied as-is on build and can only be referenced via <script src> or <link href> in html. If you want to get the URL of that file, use /xxxx.min.css?url instead.

Update this message to also add "or use the head params of starlight config"

Why is this feature necessary?

Because the head configuration is the solution

Do you have examples of this feature in other projects?

No response

Participation

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

[delucis]

Using head here is one solution, but actually it would be better in this case to move the file somewhere inside the src/ directory and use it via customCss. That allows Astro to bundle the CSS and give it a hashed file name to support long caching times.

The error you’re seeing is from Astro itself rather than Starlight, but we may potentially still be able to detect use of files in public early and provide better feedback than Astro does. For example, to say something like:

Cannot use file `downloaded/katex.min.css` in Starlight’s `customCss` config because it is inside `public/`. Please move this file to somewhere in your `src/` directory.

[Its-Just-Nans]

Hi

Yes catching the error and changing the message would be the solution I think about.

The thing is sometimes we want CSS to be in public, so the head element is the solution is this (particular) case. So the error message could be modified to add "or use the startlight head property"

[delucis]

Thanks, good to know! What's your use case for needing it in public?

[Its-Just-Nans]

If I want to expose the raw CSS file for others to use directly, I can host the file myself and provide a public URL. That way, anyone can link to it without relying on a third-party CDN

If I want to avoid depending myself on an external CDN, I can download the CSS file from the CDN and serve it locally from my own server. This ensures the file is always available, even if the CDN is unreachable.