Skip to content

docs: add <StarlightPage> import order guidelines #3199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 26, 2025
Merged

docs: add <StarlightPage> import order guidelines #3199

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1d35a18
docs: add `<StarlightPage>` import order guidelines
HiDeoo May 13, 2025
3a06c99
New lines
HiDeoo Jun 26, 2025
0943c8c
Merge branch 'main' into hd-docs-starlight-page-cascade-layers
HiDeoo Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/src/content/docs/guides/pages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,16 @@ Read more in the [“Pages” guide in the Astro docs](https://docs.astro.build/

To use the Starlight layout in custom pages, wrap your page content with the [`<StarlightPage>` component](#starlightpage-component).
This can be helpful if you are generating content dynamically but still want to use Starlight’s design.
This component must be the first import in your file to set up [cascade layers](/guides/css-and-tailwind/#cascade-layers) and ensure a predictable CSS order.

To add anchor links to headings that match Starlight’s Markdown anchor link styles, you can use the [`<AnchorHeading>` component](#anchorheading-component) in your custom pages.

```astro
---
// src/pages/custom-page/example.astro
// Import the `<StarlightPage>` component first to set up cascade layers.
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
// Import any other components you want to use in your custom page.
import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
import CustomComponent from './CustomComponent.astro';
---
Expand All @@ -105,6 +108,7 @@ The `<StarlightPage />` component renders a full page of content using Starlight

```astro
---
// Import the `<StarlightPage>` component first to set up cascade layers.
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
---

Expand All @@ -113,6 +117,8 @@ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
</StarlightPage>
```

Due to how [import order](https://docs.astro.build/en/guides/styling/#import-order) works in Astro, the `<StarlightPage />` component must be the first import in your file to set up [cascade layers](/guides/css-and-tailwind/#cascade-layers) used internally by Starlight to manage the order of its styles.

The `<StarlightPage />` component accepts the following props.

##### `frontmatter`
Expand Down