You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
In a Starlight content page, we have full control over the CSS import order and we are making sure that CSS files are imported in the correct order to properly support cascade layers.
However, in custom pages using <StarlightPage>, due to how import order for stylesheets works in Astro, we are not enforcing such order.
This means that the same custom page can ends up with broken styles depending on the order in which components are imported.
For example, the following custom page work as expected as <StarlightPage> is imported first which will import <Page> which will import the CSS files linked previously:
However, having the <AnchorHeading> or <Aside> component imported first will break the expected order as these components include styles using layers which will end up being ordered by order of usage/import.
To prevent this issue in custom pages, this PR moves the user and Starlight laer definitions to a new file which is now imported first in the <AnchorHeading> and the components.ts barrel file.
To reproduce the issue locally, comment the changes in packages/starlight/components.ts and packages/starlight/components/AnchorHeading.astro and visit the test pages included in this PR at http://localhost:4321/tests/test2/ and http://localhost:4321/tests/test3/. You should see the styles broken in both pages. After applying the changes, the styles should be fixed.
Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.
This PR includes no changesets
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
1 paths audited Performance: 93 (🔴 down 7 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports
Sharing some testing notes here in public so I don’t lose them:
This PR’s a11y checks were failing because the changes here impacted the order of styles when bundled for production, changing how cascade layers were ordered. This made our starlight.content layer take precedence over starlight.components (causing failing color contrast for links in asides).
From a quick look at the deployment preview, the order in <head> in this PR is now:
Link to print stylesheet.
Link to main stylesheet, which includes most of our base, reset, utils, and core layer styles.
Inline <style> that includes (in order): user custom CSS, our layer order statement, and then the components layer.
I guess basically something like this is happening:
When there are no custom pages, Vite/Astro bundles all CSS into one file because all routes using Starlight styles are considered a “single” route (our [...slug] route). In this case, the order we set up in the Page component is respected.
When there are custom pages, Vite/Astro splits CSS into chunks with the aim of only including styles on the routes that use them (in this case, seeing custom routes as distinct from Starlight’s catch-all route). When this happens, it’s possible for some styles to end up in the “wrong” one of these chunks and that appears to be happening to user CSS and our @layer ordering, which are in the inline “component” chunk.
This has presumably always happened, but the change in order didn’t have the same side effect that it now does with @layer.
🌟 coreChanges to Starlight’s main package📚 docsDocumentation website changes
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
github-actions
bot
added
📚 docs
Description
In a Starlight content page, we have full control over the CSS import order and we are making sure that CSS files are imported in the correct order to properly support cascade layers.
However, in custom pages using
<StarlightPage>, due to how import order for stylesheets works in Astro, we are not enforcing such order.This means that the same custom page can ends up with broken styles depending on the order in which components are imported.
For example, the following custom page work as expected as
<StarlightPage>is imported first which will import<Page>which will import the CSS files linked previously:However, having the
<AnchorHeading>or<Aside>component imported first will break the expected order as these components include styles using layers which will end up being ordered by order of usage/import.To prevent this issue in custom pages, this PR moves the user and Starlight laer definitions to a new file which is now imported first in the
<AnchorHeading>and thecomponents.tsbarrel file.To reproduce the issue locally, comment the changes in
packages/starlight/components.tsandpackages/starlight/components/AnchorHeading.astroand visit the test pages included in this PR athttp://localhost:4321/tests/test2/andhttp://localhost:4321/tests/test3/. You should see the styles broken in both pages. After applying the changes, the styles should be fixed.