Merge branch 'main' into chris/pagefind-logging

.changeset/dull-mice-live.md

@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight': minor
+---
+
+Updates `astro-expressive-code` dependency to the latest version (0.39).
+
+This includes an update to the latest Shiki version (1.26.1), providing access to all current Shiki themes and syntax highlighting languages. It also adds the config options `shiki.engine`, `shiki.bundledLangs`, `shiki.langAlias` and `removeUnusedThemes`. See the [Expressive Code release notes](https://expressive-code.com/releases/#0390) for full details.

.changeset/sweet-gorillas-refuse.md

@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Adds a print stylesheet to improve the appearance of Starlight docs pages when printed

.changeset/tender-tools-kick.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Fixes a documentation link in the JSDoc comment for the `StarlightExpressiveCodeOptions` type

.changeset/warm-coins-refuse.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Fixes colour contrast correction in code blocks

docs/src/components/sidebar-preview.astro

@@ -54,6 +54,7 @@ function makeEntries(items: SidebarConfig): SidebarEntry[] {
 		background-color: var(--sl-color-bg-sidebar);
 		border: 1px solid var(--sl-color-gray-5);
 		padding: 1rem var(--sl-sidebar-pad-x);
-		max-width: var(--sl-sidebar-width);
+		/* Matches `var(--sl-sidebar-width)`, but hardcoded to avoid being overridden when printing the page. */
+		max-width: 18.75rem;
 	}
 </style>

docs/src/content/docs/fr/resources/community-content.mdx

@@ -30,6 +30,21 @@ Voici une collection de publications et d'articles pour en apprendre plus sur St
 		title="Comparaison des générateurs de sites de documentation : VuePress contre Starlight"
 		description="Comment les deux frameworks se comparent-ils ?"
 	/>
+	<LinkCard
+		href="https://astro.build/case-studies/wp-engine/"
+		title="Étude de cas : Réduction des coûts de développement"
+		description="Comment WP Engine a réduit ses coûts de développement par plus de 50 % avec Astro Starlight."
+	/>
+	<LinkCard
+		href="https://maciekpalmowski.dev/blog/building-a-documentation-site-using-astro-starlight/"
+		title="Construction d'un site de documentation avec Astro Starlight"
+		description="Maciek Palmowski décrit comment Patchstack a migré sa documentation vers Starlight"
+	/>
+	<LinkCard
+		href="https://blog.cloudflare.com/open-source-all-the-way-down-upgrading-our-developer-documentation/"
+		title="Open source du début à la fin"
+		description="Comment Cloudflare a utilisé Starlight pour mettre à jour sa documentation pour les développeurs."
+	/>
 </CardGrid>
 
 ## Recettes et guides

docs/src/content/docs/fr/resources/plugins.mdx

@@ -135,6 +135,11 @@ Un thème est un module d'extension Starlight qui modifie l'apparence visuelle d
 		title="catppuccin-starlight"
 		description="Thème apaisant aux couleurs pastel pour Starlight"
 	/>
+	<LinkCard
+		href="https://github.com/louisescher/starlight-ion-theme"
+		title="starlight-ion-theme"
+		description="Un thème élégant et moderne pour Starlight."
+	/>
 </CardGrid>
 
 ## Outils et intégrations communautaires

docs/src/content/docs/guides/authoring-content.mdx

@@ -220,24 +220,24 @@ var fun = function lang(l) {
 
 ### Expressive Code features
 
-Starlight uses [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) to extend formatting possibilities for code blocks.
+Starlight uses [Expressive Code](https://expressive-code.com/) to extend formatting possibilities for code blocks.
 Expressive Code’s text markers and window frames plugins are enabled by default.
 Code block rendering can be configured using Starlight’s [`expressiveCode` configuration option](/reference/configuration/#expressivecode).
 
 #### Text markers
 
-You can highlight specific lines or parts of your code blocks using [Expressive Code text markers](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#usage-in-markdown--mdx-documents) on the opening line of your code block.
+You can highlight specific lines or parts of your code blocks using [Expressive Code text markers](https://expressive-code.com/key-features/text-markers/) on the opening line of your code block.
 Use curly braces (`{ }`) to highlight entire lines, and quotation marks to highlight strings of text.
 
 There are three highlighting styles: neutral for calling attention to code, green for indicating inserted code, and red for indicating deleted code.
 Both text and entire lines can be marked using the default marker, or in combination with `ins=` and `del=` to produce the desired highlighting.
 
 Expressive Code provides several options for customizing the visual appearance of your code samples.
 Many of these can be combined, for highly illustrative code samples.
-Please explore the [Expressive Code documentation](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md) for the extensive options available.
+Please explore the [Expressive Code documentation](https://expressive-code.com/key-features/text-markers/#configuration) for the extensive options available.
 Some of the most common examples are shown below:
 
-- [Mark entire lines & line ranges using the `{ }` marker](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-entire-lines--line-ranges):
+- [Mark entire lines & line ranges using the `{ }` marker](https://expressive-code.com/key-features/text-markers/#marking-full-lines--line-ranges):
 
   ```js {2-3}
   function demo() {
@@ -255,7 +255,7 @@ Some of the most common examples are shown below:
   ```
   ````
 
-- [Mark selections of text using the `" "` marker or regular expressions](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-individual-text-inside-lines):
+- [Mark selections of text using the `" "` marker or regular expressions](https://expressive-code.com/key-features/text-markers/#marking-individual-text-inside-lines):
 
   ```js "Individual terms" /Even.*supported/
   // Individual terms can be highlighted, too
@@ -273,7 +273,7 @@ Some of the most common examples are shown below:
   ```
   ````
 
-- [Mark text or lines as inserted or deleted with `ins` or `del`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#selecting-marker-types-mark-ins-del):
+- [Mark text or lines as inserted or deleted with `ins` or `del`](https://expressive-code.com/key-features/text-markers/#selecting-inline-marker-types-mark-ins-del):
 
   ```js "return true;" ins="inserted" del="deleted"
   function demo() {
@@ -293,7 +293,7 @@ Some of the most common examples are shown below:
   ```
   ````
 
-- [Combine syntax highlighting with `diff`-like syntax](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#combining-syntax-highlighting-with-diff-like-syntax):
+- [Combine syntax highlighting with `diff`-like syntax](https://expressive-code.com/key-features/text-markers/#combining-syntax-highlighting-with-diff-like-syntax):
 
   ```diff lang="js"
     function thisIsJavaScript() {
@@ -323,7 +323,7 @@ Other languages display inside a code editor-style frame if they include a title
 
 A code block’s optional title can be set either with a `title="..."` attribute following the code block's opening backticks and language identifier, or with a file name comment in the first lines of the code.
 
-- [Add a file name tab with a comment](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title)
+- [Add a file name tab with a comment](https://expressive-code.com/key-features/frames/#code-editor-frames)
 
   ```js
   // my-test-file.js
@@ -337,7 +337,7 @@ A code block’s optional title can be set either with a `title="..."` attribute
   ```
   ````
 
-- [Add a title to a Terminal window](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title)
+- [Add a title to a Terminal window](https://expressive-code.com/key-features/frames/#terminal-frames)
 
   ```bash title="Installing dependencies…"
   npm install
@@ -349,7 +349,7 @@ A code block’s optional title can be set either with a `title="..."` attribute
   ```
   ````
 
-- [Disable window frames with `frame="none"`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#overriding-frame-types)
+- [Disable window frames with `frame="none"`](https://expressive-code.com/key-features/frames/#overriding-frame-types)
 
   ```bash frame="none"
   echo "This is not rendered as a terminal despite using the bash language"

docs/src/content/docs/guides/i18n.mdx

@@ -221,7 +221,7 @@ You can provide translations for additional languages you support — or overrid
 
    <UIStringsList />
 
-   Starlight’s code blocks are powered by the [Expressive Code](https://github.com/expressive-code/expressive-code) library.
+   Starlight’s code blocks are powered by the [Expressive Code](https://expressive-code.com/) library.
    You can set translations for its UI strings in the same JSON file using `expressiveCode` keys:
 
    ```json

docs/src/content/docs/ko/resources/community-content.mdx

@@ -30,39 +30,54 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components';
 		title="문서 사이트 빌더 비교: VuePress vs Starlight"
 		description="이 두 프레임워크는 어떻게 비교되나요?"
 	/>
+	<LinkCard
+		href="https://astro.build/case-studies/wp-engine/"
+		title="사례 연구: 개발 비용 절감"
+		description="WP Engine이 Astro의 Starlight로 개발 비용을 50% 이상 절감한 방법"
+	/>
+	<LinkCard
+		href="https://maciekpalmowski.dev/blog/building-a-documentation-site-using-astro-starlight/"
+		title="Astro의 Starlight를 사용한 문서 사이트 구축"
+		description="Patchstack 문서를 Starlight로 마이그레이션하는 과정 - Maciek Palmowski"
+	/>
+	<LinkCard
+		href="https://blog.cloudflare.com/open-source-all-the-way-down-upgrading-our-developer-documentation/"
+		title="오픈소스의 힘으로"
+		description="Cloudflare가 Starlight로 개발자 문서를 개선한 방법"
+	/>
 </CardGrid>
 
-## 레시피 및 안내서
+## 레시피 및 가이드
 
-레시피는 일반적으로 특정 작업의 실제 예시를 완료하는 과정을 독자에게 안내하는 짧고 집중적인 방법 안내서입니다. 레시피는 단계별 지침에 따라 Starlight 프로젝트에 새로운 기능이나 동작을 추가할 수 있는 좋은 방법입니다! 다른 안내서에서는 이미지 사용이나 MDX 작업 등 콘텐츠 영역과 관련된 개념을 설명할 수도 있습니다.
+레시피는 일반적으로 특정 작업의 실제 예시를 완료하는 과정을 독자에게 안내하는 짧고 집중적인 가이드입니다. 레시피는 단계별 지침에 따라 Starlight 프로젝트에 새로운 기능이나 동작을 추가할 수 있는 좋은 방법입니다! 다른 가이드에서는 이미지 사용이나 MDX 작업 등 콘텐츠 영역과 관련된 개념을 설명할 수도 있습니다.
 
 Starlight 사용자들이 관리하는 커뮤니티 제작 콘텐츠를 살펴보세요.
 
 <CardGrid>
 	<LinkCard
 		href="https://www.webpro.nl/scraps/versioned-docs-with-starlight-and-vercel"
 		title="Starlight & Vercel을 사용한 버전별 문서"
-		description="프로젝트의 각 주요 버전에 대해 별도의 문서 버전을 구현하는 방법에 대한 안내서"
+		description="프로젝트의 각 주요 버전에 대해 별도의 문서 버전을 구현하는 방법에 대한 가이드"
 	/>
 	<LinkCard
 		href="https://hideoo.dev/notes/starlight-heading-links"
 		title="Starlight 제목에 링크 추가"
-		description="문서의 특정 섹션에 대한 링크를 공유하기 위한 rehype 플러그인 사용 안내서"
+		description="문서의 특정 섹션에 대한 링크를 공유하기 위한 rehype 플러그인 사용 가이드"
 	/>
 	<LinkCard
 		href="https://blog.otterlord.dev/posts/starlight-sponsors/"
 		title="Starlight 사이트에 스폰서 추가"
-		description="문서 사이드바에 맞춤 스폰서 컴포넌트를 구현하기 위한 안내서"
+		description="문서 사이드바에 맞춤 스폰서 컴포넌트를 구현하기 위한 가이드"
 	/>
 	<LinkCard
 		href="https://hideoo.dev/notes/starlight-og-images"
 		title="Starlight에 Open Graph 이미지 추가"
-		description="페이지에 대한 소셜 이미지 및 해당 메타 태그 생성에 대한 안내서"
+		description="페이지에 대한 소셜 이미지 및 해당 메타 태그 생성에 대한 가이드"
 	/>
 	<LinkCard
 		href="https://hideoo.dev/notes/starlight-third-party-icon-sets"
 		title="Starlight에서 타사 아이콘 세트 사용"
-		description="unplugin-icons를 사용하여 Starlight에 사용 가능한 아이콘 선택 범위를 확장하는 방법에 대한 안내서"
+		description="unplugin-icons를 사용하여 Starlight에 사용 가능한 아이콘 선택 범위를 확장하는 방법에 대한 가이드"
 	/>
 	<LinkCard
 		href="https://hideoo.dev/notes/starlight-custom-html-head"

docs/src/content/docs/ko/resources/plugins.mdx

@@ -135,6 +135,11 @@ Starlight 팀이 지원하는 공식 플러그인과 Starlight 사용자가 관
 		title="catppuccin-starlight"
 		description="Starlight를 위한 차분한 파스텔 테마"
 	/>
+	<LinkCard
+		href="https://github.com/louisescher/starlight-ion-theme"
+		title="starlight-ion-theme"
+		description="Starlight를 위한 세련되고 현대적인 테마"
+	/>
 </CardGrid>
 
 ## 커뮤니티 도구 및 통합

docs/src/content/docs/reference/configuration.mdx

@@ -384,10 +384,10 @@ starlight({
 **type:** `StarlightExpressiveCodeOptions | boolean`  
 **default:** `true`
 
-Starlight uses [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) to render code blocks and add support for highlighting parts of code examples, adding filenames to code blocks, and more.
+Starlight uses [Expressive Code](https://expressive-code.com) to render code blocks and add support for highlighting parts of code examples, adding filenames to code blocks, and more.
 See the [“Code blocks” guide](/guides/authoring-content/#code-blocks) to learn how to use Expressive Code syntax in your Markdown and MDX content.
 
-You can use any of the standard [Expressive Code configuration options](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#configuration) as well as some Starlight-specific properties, by setting them in Starlight’s `expressiveCode` option.
+You can use any of the standard [Expressive Code configuration options](https://expressive-code.com/reference/configuration/) as well as some Starlight-specific properties, by setting them in Starlight’s `expressiveCode` option.
 For example, set Expressive Code’s `styleOverrides` option to override the default CSS. This enables customizations like giving your code blocks rounded corners:
 
 ```js ins={2-4}
@@ -414,7 +414,7 @@ In addition to the standard Expressive Code options, you can also set the follow
 **default:** `['starlight-dark', 'starlight-light']`
 
 Set the themes used to style code blocks.
-See the [Expressive Code `themes` documentation](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#themes) for details of the supported theme formats.
+See the [Expressive Code `themes` documentation](https://expressive-code.com/guides/themes/) for details of the supported theme formats.
 
 Starlight uses the dark and light variants of Sarah Drasner’s [Night Owl theme](https://github.com/sdras/night-owl-vscode-theme) by default.
 

docs/src/content/docs/resources/community-content.mdx

@@ -30,6 +30,21 @@ Here is a collection of posts and articles to learn more about Starlight and oth
 		title="Comparing docs site builders: VuePress vs Starlight"
 		description="How do these two frameworks measure up?"
 	/>
+	<LinkCard
+		href="https://astro.build/case-studies/wp-engine/"
+		title="Case Study: Slashing Development Costs"
+		description="How WP Engine Lowered Development Costs by Over 50% with Astro’s Starlight."
+	/>
+	<LinkCard
+		href="https://maciekpalmowski.dev/blog/building-a-documentation-site-using-astro-starlight/"
+		title="Building a documentation site using Astro Starlight"
+		description="Maciek Palmowski describes how Patchstack migrated their documentation to Starlight"
+	/>
+	<LinkCard
+		href="https://blog.cloudflare.com/open-source-all-the-way-down-upgrading-our-developer-documentation/"
+		title="Open source all the way down"
+		description="How Cloudflare used Starlight to upgrade their developer documentation."
+	/>
 </CardGrid>
 
 ## Recipes and Guides

docs/src/content/docs/resources/plugins.mdx

@@ -135,6 +135,11 @@ A theme is a Starlight plugin that changes the visual appearance of a site with
 		title="catppuccin-starlight"
 		description="Soothing pastel theme for Starlight"
 	/>
+	<LinkCard
+		href="https://github.com/louisescher/starlight-ion-theme"
+		title="starlight-ion-theme"
+		description="A sleek, modern theme for Starlight."
+	/>
 </CardGrid>
 
 ## Community tools and integrations

package.json

@@ -38,7 +38,10 @@
     },
     {
       "name": "/_astro/*.css",
-      "path": "examples/basics/dist/_astro/*.css",
+      "path": [
+        "examples/basics/dist/_astro/*.css",
+        "!examples/basics/dist/_astro/print.*.css"
+      ],
       "limit": "14.5 kB",
       "gzip": true
     }

packages/starlight/components/EditLink.astro

@@ -7,7 +7,7 @@ const { editUrl } = Astro.props;
 
 {
 	editUrl && (
-		<a href={editUrl} class="sl-flex">
+		<a href={editUrl} class="sl-flex print:hidden">
 			<Icon name="pencil" size="1.2em" />
 			{Astro.locals.t('page.editLink')}
 		</a>

packages/starlight/components/Header.astro

@@ -19,10 +19,10 @@ const shouldRenderSearch =
 	<div class="title-wrapper sl-flex">
 		<SiteTitle {...Astro.props} />
 	</div>
-	<div class="sl-flex">
+	<div class="sl-flex print:hidden">
 		{shouldRenderSearch && <Search {...Astro.props} />}
 	</div>
-	<div class="sl-hidden md:sl-flex right-group">
+	<div class="sl-hidden md:sl-flex print:hidden right-group">
 		<div class="sl-flex social-icons">
 			<SocialIcons {...Astro.props} />
 		</div>

packages/starlight/components/MobileMenuToggle.astro

@@ -3,7 +3,7 @@ import type { Props } from '../props';
 import Icon from '../user-components/Icon.astro';
 ---
 
-<starlight-menu-button>
+<starlight-menu-button class="print:hidden">
 	<button
 		aria-expanded="false"
 		aria-label={Astro.locals.t('menuButton.accessibleLabel')}

packages/starlight/components/Page.astro

@@ -31,6 +31,8 @@ import '../style/asides.css';
 // Important that this is the last import so it can override built-in styles.
 import 'virtual:starlight/user-css';
 
+import printHref from '../style/print.css?url&no-inline';
+
 const pagefindEnabled =
 	Astro.props.entry.slug !== '404' &&
 	!Astro.props.entry.slug.endsWith('/404') &&
@@ -75,6 +77,7 @@ if (pagefindEnabled) mainDataAttributes['data-pagefind-body'] = '';
 			}
 		</style>
 		<ThemeProvider {...Astro.props} />
+		<link rel="stylesheet" href={printHref} media="print" />
 	</head>
 	<body>
 		<SkipLink {...Astro.props} />

packages/starlight/components/PageFrame.astro

@@ -9,7 +9,7 @@ const { hasSidebar } = Astro.props;
 	<header class="header"><slot name="header" /></header>
 	{
 		hasSidebar && (
-			<nav class="sidebar" aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}>
+			<nav class="sidebar print:hidden" aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}>
 				<MobileMenuToggle {...Astro.props} />
 				<div id="starlight__sidebar" class="sidebar-pane">
 					<div class="sidebar-content sl-flex">

packages/starlight/components/Pagination.astro

@@ -7,7 +7,7 @@ const { prev, next } = pagination;
 const isRtl = dir === 'rtl';
 ---
 
-<div class="pagination-links" dir={dir}>
+<div class="pagination-links print:hidden" dir={dir}>
 	{
 		prev && (
 			<a href={prev.href} rel="prev">

packages/starlight/components/SiteTitle.astro

@@ -10,7 +10,7 @@ const { siteTitle, siteTitleHref } = Astro.props;
 		config.logo && logos.dark && (
 			<>
 				<img
-					class:list={{ 'light:sl-hidden': !('src' in config.logo) }}
+					class:list={{ 'light:sl-hidden print:hidden': !('src' in config.logo) }}
 					alt={config.logo.alt}
 					src={logos.dark.src}
 					width={logos.dark.width}
@@ -19,7 +19,7 @@ const { siteTitle, siteTitleHref } = Astro.props;
 				{/* Show light alternate if a user configure both light and dark logos. */}
 				{!('src' in config.logo) && (
 					<img
-						class="dark:sl-hidden"
+						class="dark:sl-hidden print:block"
 						alt={config.logo.alt}
 						src={logos.light?.src}
 						width={logos.light?.width}