Description
This issue is more of an umbrella for the various issues and feedback gathered regarding the style changes from Starlight 0.34.0 and the switch to cascade layers.
Technical issues
1. Missing styles
Workaround shipped in Starlight 0.34.2
History
Not technically related to the changes in 0.34.0, but seems to be more easily reproducible due to some refactoring in this release. If an integration or Starlight plugin injecting dynamic routes that also render the <StarlightPage> component, due to an head propagation issue, some styles can end up missing in development mode.
- Tracked in Missing styles due to head propagation issue astro#13724
- Initially, I opened a workaround PR before investigating the issue
- After having investigated the issue, I implemented a better and documented workaround with an E2E test that we can decided to ship if the Astro issue is not something that can be easily fixed
2. Custom pages layer order
For custom pages rendered using the <StarlightPage> component, due to how import order for stylesheets works in Astro, importing <AnchorHeading> or any Starlight component before <StarlightPage> breaks the expected layer order as we cannot control the order in this case like we do for Starlight pages.
- Opened a tentative PR to fix this issue but ended up fixing the issue in dev but breaking in production
- Need to investigate further if we can somehow reliably enforce the order in such cases
- If not, we would need to document this behavior and suggest to import
<StarlightPage>before any other Starlight component
Documentation feedback
3. Do I have to use cascade layers?
Documentation updated in #3167 and we will monitor for extra feedback to see if we need to improve the documentation further.
History
It looks like some users could be confused by the fact that we are using cascade layers in Starlight and that they may also need to use them in their own stylesheets. The "any custom unlayered CSS will override the default styles" may not be clear enough.
- We should figure out how to emphasize that cascade layers are not mandatory for user stylesheets. Starlight use them internally, users can use them if they want to, but they are not required
4. I was expecting Starlight to override my styles, but it's no longer the case
Documentation updated in #3167 and we will monitor for extra feedback to see if we need to improve the documentation further.
History
This case is a bit more tricky as I think having authored CSS that is expected to be overridden by Starlight is a bit confusing. Altho, I guess this can happen e.g. for someone migrating to Starlight, importing all their existing custom CSS and only tweaking them enough to make them work with Starlight.
Now, with the cascade layers, any unlayered CSS will override Starlight styles, so any authored CSS will win and can lead to unexpected results.
- Not quite sure yet how to document/provide guidance for this case
5. Tailwind customCss ordering
customCss orderingDocumentation updated in #3170 and we will monitor for extra feedback to see if we need to improve the documentation further.
History
A few users have already run in this issue where their ./src/styles/global.css was not being the first element in the customCss array which can definitely cause unexpected behavior.
- Maybe a mention about the ordering could be made in step 4 of https://starlight.astro.build/guides/css-and-tailwind/#add-tailwind-to-an-existing-project
6. I'm using custom pages or Starlight at a subpath and want Tailwind on both my site/custom pages and Starlight.
When using custom pages or Starlight at a subpath and want to use Tailwind on both your main site/custom pages and Starlight, you propably want to use a default Tailwind setup for your main website and a different one for Starlight which would use the Starlight’s Tailwind compatibility package.
This has already been asked quite a bit of times, and even tho it's a bit similar to how this used to work with Tailwind v3, it may not be obvious that you want to use different CSS files.
-
For the main website, one CSS file that will probably be imported in a layout component
@import "tailwindcss";
-
For Starlight, the one we document that will be referenced in Starlight
customCssconfig option.@layer base, starlight, theme, components, utilities; @import '@astrojs/starlight-tailwind'; @import 'tailwindcss/theme.css' layer(theme); @import 'tailwindcss/utilities.css' layer(utilities);
- Figure out if we can hint at this in the documentation
Participation
- I am willing to submit a pull request for this issue.