Don’t apply Starlight code blocks in non-starlight routes

[jpal91]

What version of starlight are you using?

0.31.1

What version of astro are you using?

5.1.7

What package manager are you using?

pnpm

What operating system are you using?

Linux

What browser are you using?

Chrome

Describe the Bug

Expected

Starlight will only apply styling to code blocks in Starlight routes when integrated in an existing project.

Actual

When attempting to integrate Starlight in an existing project, Starlight overrides existing styling/mdx in non-Starlight routes.

Explanation

In the included example, I added a new page in the blog collection which has a code block. The code block is derived from a custom mdx component and included in the components props in src/pages/blog/[...slug].astro. This should override any pre tags and render the custom component instead.

After the integration is added, the code block gets wrapped in the .expressive-code div which appears to strip all existing styling and add a figure wrapper. You could theoretically do document.querySelector(...).replaceWith(...), but even then, the code block has already lost any shiki styling that would have been applied before.

Reproduce

1. Go to the example and navigate to blog/example. You will see a code block that has default shiki styling and a daisyui utility class.
2. Ctrl + C, go to astro.config, uncomment the starlight integration.
3. Go back to blog/example and you'll see the changes.
4. (Optional) Remove the comment block around the script block src/components/Code.astro to see the parent Starlight block replaced with the child. It looks back to normal, except no shiki styling.

Suggestions

Although I tried to look through the source code and figure out how and when Starlight's Code was being injected, or if it had something to do with overriding the mdx integration, I couldn't quite figure it out. Maybe if I had more time later, I could look through the source code if any of my suggestions are too difficult to implement as is. However, if any of the following are possible, that would be great!

1. Restrict Starlight to it's routes. I would assume this would be the case with content collections, but I'm guessing Starlight's Code interacts with the content collections in a different way than normal or overrides the mdx integration somehow.
2. Make Starlight's Code component override-able. It appears that Code is the only component you can't override unfortunately. This could be an easy fix...
3. Add an option in the integration to output the code block without any kind of wrapper, essentially ignoring them and output a pre. This would require devs to apply everything manually, but it could work.

---

I would really love to avoid having to create a separate project and also have to deal with subdomains to add docs to a site, but if Starlight is going to impact other routes unrelated to it, it seems like there isn't any other option. If I'm missing something totally obvious, though, please let me know as that would make me very happy!

Lastly, I am a big fan of the project and really appreciate all the hard work every one is doing on it!

Link to Minimal Reproducible Example

https://codesandbox.io/p/sandbox/goofy-wood-xnw3py

Participation

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

[delucis]

Thanks for the issue @jpal91 — this is due to Expressive Code running for all Markdown/MDX content in a project, which is semi expected, but I understand sometimes doesn't work if a site has distinct theming for different sections.

First up a couple of workarounds:

• You can set expressiveCode: false in your Starlight configuration to use Astro's default syntax highlighting. Depending on whether the rest of your site's styles look ok on Starlight pages, this may or may not be acceptable.

• You can use Expressive Code's options to customise how things look to match your existing styles. This might take slightly longer, but for basic stuff like syntax theme etc. it can be pretty quick.

Regarding the general issue: it may be possible for Expressive Code to skip certain files with an added configuration options. During Markdown processing, plugins like this have access to the current file path, so in theory it could be possible for a plugin to have an option e.g. to only apply to src/content/docs/**. Paging @hippotastic for thoughts!

[hippotastic]

Thank you for bringing this up. I understand the issue - the current implementation of Starlight's Expressive Code integration doesn't account for "hybrid projects" like this. Also, the last time I had a look at such projects, they were not fully supported by Starlight either and the recommendation was to set up a separate Starlight project for docs. Has this changed and limiting Starlight to a subpath of an existing site fully works and is supported?

The solution of setting expressiveCode: false in your Starlight config as described by @delucis should work well.

If you want to keep using Expressive Code in the Starlight part of your site, but use something else for the rest of your site, I'd need to change the implementation of both astro-expressive-code and rehype-expressive-code to allow limiting its Markdown/MDX processing to certain routes. This could be through an Expressive Code-specific path matching option as proposed, but I would have preferred to use a Starlight-provided subpath option instead, which currently does not exist to my knowledge. I'm also currently setting markdown: { syntaxHighlight: false } in the Astro config to prevent any chance of unwanted double processing, which would also need to be disabled in such cases.

[delucis]

Also, the last time I had a look at such projects, they were not fully supported by Starlight either and the recommendation was to set up a separate Starlight project for docs. Has this changed and limiting Starlight to a subpath of an existing site fully works and is supported?

Hmm, as far as I know, we’ve always supported this! There’s no special code involved, but we document it here: https://starlight.astro.build/manual-setup/#use-starlight-at-a-subpath

If EC offered a path matching option, then Starlight could in theory tell EC to only apply to src/content/docs/**/*.{md,mdx}. The only issue on EC’s end I guess is whether it supports multiple instances? Like if you wanted one set of EC configuration for docs and another for your blog would you add EC twice with different glob patterns? There’s probably a few details to figure out.

Given this, I think I’ll move this issue to our feature requests as it will likely rely on some bigger upstream work.

[delucis]

which 404 handler is going to apply for a given path

Yeah that’s a generic issue for static sites — by default most static hosts only support a root 404.html out of the box (although with some it’s fairly easy to customize). But Starlight has a disable404Route for this reason to allow people to render their own 404 instead of Starlight’s if they want.

does the link checker know to restrict its duties to the Starlight portion only?

Good question! @HiDeoo would know for sure.

Do themes only apply to the Starlight portion of the page

In general they should yeah if they are only providing overrides, adding customCSS values etc. Those are all scoped to Starlight’s pages. It is definitely still possible for a theme to bleed (in the end they can do anything an integration can, so we can’t isolate things 100%), but I don’t think they should in most common cases.

[HiDeoo]

does the link checker know to restrict its duties to the Starlight portion only?

It does not by default (on purpose) but can be configured to do so. I think it's also a bit different for remark/rehype plugins that changes the output vs some other process that does not.

[delucis]

Btw, if EC had such an option, I probably wouldn’t suggest it being enabled by default — in many cases consistent code blocks across the site is a benefit. But it would be handy I guess if users could set something like expressiveCode: { starlightOnly: true } and we automatically handled that for those who need it.

[hippotastic]

While I understand the idea, I think it might actually be a good idea to enable it by default, as Starlight's EC integration applies some settings that make the output rely on Starlight CSS variables and styles that might not be present on the rest of the site.

I see a practical problem with enabling it by default though as I don't know how to determine the patterns to match automatically. Users might have changed their content collection configuration.

Maybe we can just consider this an advanced use case that warrants manual configuration. Then it would be hopefully easy to implement.

[delucis]

Users might have changed their content collection configuration.

Currently we only support src/content/docs/* for content officially. Although admittedly I think a few people have hacked around it. Still, for full-featured support for stuff like i18n, edit links, Git last-modified dates etc., you have to stick to the classic folder structure.

But yeah, the simplest starting point is an EC option that includes/excludes files and then as a Starlight user you can pass that like you would any other EC config option. We can always improve on that approach later.

[jpal91]

I want to thank everyone that responded back to this to provide feedback/insight. I don't have the time tonight to try out some of these suggestions and report back, but I should be able to tomorrow. I do appreciate everyone sharing their expertise.

Again, thank you for all the hard work! The limited experience I have with a Starlight page was pretty amazing, so I know this is definitely something I want to try to get integrated into a project.