@astrojs/starlight 0.33.2 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # @astrojs/starlight
 
+## 0.34.0
+
+### Minor Changes
+
+- [#2322](https://github.com/withastro/starlight/pull/2322) [`f14eb0c`](https://github.com/withastro/starlight/commit/f14eb0cd7baa0391d6124379f6c5df4b9ab7cc44) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Groups all of Starlight's CSS declarations into a single `starlight` [cascade layer](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers).
+
+  This change allows for easier customization of Starlight's CSS as any custom unlayered CSS will override the default styles. If you are using cascade layers in your custom CSS, you can use the [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) CSS at-rule to define the order of precedence for different layers including the ones used by Starlight.
+
+  We recommend checking your site’s appearance when upgrading to make sure there are no style regressions caused by this change.
+
+- [#3122](https://github.com/withastro/starlight/pull/3122) [`3a087d8`](https://github.com/withastro/starlight/commit/3a087d8fbcd946336f8a0423203967e53e5678fe) Thanks [@delucis](https://github.com/delucis)! - Removes default `attrs` and `content` values from head entries parsed using Starlight’s schema.
+
+  Previously when adding `head` metadata via frontmatter or user config, Starlight would automatically add values for `attrs` and `content` if not provided. Now, these properties are left `undefined`.
+
+  This makes it simpler to add tags in route middleware for example as you no longer need to provide empty values for `attrs` and `content`:
+
+  ```diff
+  head.push({
+    tag: 'style',
+    content: 'div { color: red }'
+  - attrs: {},
+  });
+  head.push({
+    tag: 'link',
+  - content: ''
+    attrs: { rel: 'me', href: 'https://example.com' },
+  });
+  ```
+
+  This is mostly an internal API but if you are overriding Starlight’s `Head` component or processing head entries in some way, you may wish to double check your handling of `Astro.locals.starlightRoute.head` is compatible with `attrs` and `content` potentially being `undefined`.
+
+- [#3033](https://github.com/withastro/starlight/pull/3033) [`8c19678`](https://github.com/withastro/starlight/commit/8c19678e57c0270d3d80d4678f23a6fc287ebf12) Thanks [@delucis](https://github.com/delucis)! - Adds support for generating clickable anchor links for headings.
+
+  By default, Starlight now renders an anchor link beside headings in Markdown and MDX content. A new `<AnchorHeading>` component is available to achieve the same thing in custom pages built using `<StarlightPage>`.
+
+  If you want to disable this new Markdown processing set the `markdown.headingLinks` option in your Starlight config to `false`:
+
+  ```js
+  starlight({
+    title: 'My docs',
+    markdown: {
+      headingLinks: false,
+    },
+  }),
+  ```
+
+  ⚠️ **BREAKING CHANGE:** The minimum supported version of Astro is now v5.5.0.
+
+  Please update Starlight and Astro together:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+- [#2322](https://github.com/withastro/starlight/pull/2322) [`f14eb0c`](https://github.com/withastro/starlight/commit/f14eb0cd7baa0391d6124379f6c5df4b9ab7cc44) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Removes Shiki `css-variables` theme fallback.
+
+  ⚠️ **BREAKING CHANGE:**
+
+  Previously, Starlight used to automatically provide a fallback theme for Shiki, the default syntax highlighter built into Astro if the configured Shiki theme was not `github-dark`.
+
+  This fallback was only relevant when the default Starlight code block renderer, Expressive Code, was disabled and Shiki was used. Starlight no longer provides this fallback.
+
+  If you were relying on this behavior, you now manually need to update your Astro configuration to use the Shiki `css-variables` theme to match the previous behavior.
+
+  ```diff
+  import { defineConfig } from 'astro/config';
+
+  export default defineConfig({
+  + markdown: {
+  +   shikiConfig: {
+  +     theme: 'css-variables',
+  +   },
+  + },
+  });
+  ```
+
+  Additionally, you can use [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) to control the appearance of the code blocks. Here are the previously used CSS variables for the fallback theme:
+
+  ```css
+  :root {
+    --astro-code-foreground: var(--sl-color-white);
+    --astro-code-background: var(--sl-color-gray-6);
+    --astro-code-token-constant: var(--sl-color-blue-high);
+    --astro-code-token-string: var(--sl-color-green-high);
+    --astro-code-token-comment: var(--sl-color-gray-2);
+    --astro-code-token-keyword: var(--sl-color-purple-high);
+    --astro-code-token-parameter: var(--sl-color-red-high);
+    --astro-code-token-function: var(--sl-color-red-high);
+    --astro-code-token-string-expression: var(--sl-color-green-high);
+    --astro-code-token-punctuation: var(--sl-color-gray-2);
+    --astro-code-token-link: var(--sl-color-blue-high);
+  }
+  ```
+
+### Patch Changes
+
+- [#3118](https://github.com/withastro/starlight/pull/3118) [`77a1104`](https://github.com/withastro/starlight/commit/77a110461dffacd1d3ee3b8934fd48b20111f3c4) Thanks [@delucis](https://github.com/delucis)! - Fixes passing imported SVGs to the `frontmatter` prop of the `<StarlightPage>` component in Astro ≥5.7.0
+
 ## 0.33.2
 
 ### Patch Changes

package/components/AnchorHeading.astro

@@ -0,0 +1,53 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import { transform } from 'ultrahtml';
+import sanitize from 'ultrahtml/transformers/sanitize';
+// These styles are included globally by default, but can be removed when `markdown.headingLinks` is
+// set to `false`. We import them here to ensure they are included if the component is used with the
+// global Markdown option disabled.
+import '../style/anchor-links.css';
+import { AstroError } from 'astro/errors';
+
+const headingLevels = [1, 2, 3, 4, 5, 6, '1', '2', '3', '4', '5', '6'] as const;
+interface Props extends HTMLAttributes<'h1'> {
+	level: 1 | 2 | 3 | 4 | 5 | 6 | `${1 | 2 | 3 | 4 | 5 | 6}`;
+	id: string;
+}
+
+const { level, id, ...attrs } = Astro.props;
+
+if (!id) {
+	throw new AstroError(
+		'Missing `id` attribute passed to `<AnchorHeading>` component',
+		`The \`<AnchorHeading>\` component requires an \`id\` attribute, but received \`${typeof id === 'string' ? '""' : id}\`.`
+	);
+}
+if (!headingLevels.includes(level)) {
+	throw new AstroError(
+		'Invalid `level` attribute passed to `<AnchorHeading>` component',
+		`The \`<AnchorHeading>\` component expects a \`level\` attribute of \`1 | 2 | 3 | 4 | 5 | 6\`, but received \`${level}\`.`
+	);
+}
+
+const HeadingElement = `h${level}` as const;
+const headingHTML = await Astro.slots.render('default');
+const headingString = await transform(headingHTML, [sanitize({ unblockElements: [] })]);
+const accessibleLabel = Astro.locals.t('heading.anchorLabel', {
+	title: headingString,
+	interpolation: { escapeValue: false },
+})
+---
+
+{/* The spacing in this component is a little awkward to ensure whitespace matches what the rehype plugin produces. */}
+<div class={`sl-heading-wrapper level-h${level}`}
+	><HeadingElement {id} {...attrs} set:html={headingHTML} /><a class="sl-anchor-link" href={`#${id}`}
+		><span aria-hidden="true" class="sl-anchor-icon"
+			><svg width="16" height="16" viewBox="0 0 24 24"
+				><path
+					fill="currentcolor"
+					d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"
+				></path></svg
+			></span
+		><span class="sr-only" set:text={accessibleLabel} /></a
+	></div
+>

package/components/Banner.astro

@@ -5,17 +5,19 @@ const { banner } = Astro.locals.starlightRoute.entry.data;
 {banner && <div class="sl-banner" set:html={banner.content} />}
 
 <style>
-	.sl-banner {
-		--__sl-banner-text: var(--sl-color-banner-text, var(--sl-color-text-invert));
-		padding: var(--sl-nav-pad-y) var(--sl-nav-pad-x);
-		background-color: var(--sl-color-banner-bg, var(--sl-color-bg-accent));
-		color: var(--__sl-banner-text);
-		line-height: var(--sl-line-height-headings);
-		text-align: center;
-		text-wrap: balance;
-		box-shadow: var(--sl-shadow-sm);
-	}
-	.sl-banner :global(a) {
-		color: var(--__sl-banner-text);
+	@layer starlight.core {
+		.sl-banner {
+			--__sl-banner-text: var(--sl-color-banner-text, var(--sl-color-text-invert));
+			padding: var(--sl-nav-pad-y) var(--sl-nav-pad-x);
+			background-color: var(--sl-color-banner-bg, var(--sl-color-bg-accent));
+			color: var(--__sl-banner-text);
+			line-height: var(--sl-line-height-headings);
+			text-align: center;
+			text-wrap: balance;
+			box-shadow: var(--sl-shadow-sm);
+		}
+		.sl-banner :global(a) {
+			color: var(--__sl-banner-text);
+		}
 	}
 </style>

package/components/ContentNotice.astro

@@ -16,16 +16,18 @@ const { icon, label } = Astro.props;
 </p>
 
 <style>
-	p {
-		border: 1px solid var(--sl-color-orange);
-		padding: 0.75em 1em;
-		background-color: var(--sl-color-orange-low);
-		color: var(--sl-color-orange-high);
-		width: max-content;
-		max-width: 100%;
-		align-items: center;
-		gap: 0.75em;
-		font-size: var(--sl-text-body-sm);
-		line-height: var(--sl-line-height-headings);
+	@layer starlight.core {
+		p {
+			border: 1px solid var(--sl-color-orange);
+			padding: 0.75em 1em;
+			background-color: var(--sl-color-orange-low);
+			color: var(--sl-color-orange-high);
+			width: max-content;
+			max-width: 100%;
+			align-items: center;
+			gap: 0.75em;
+			font-size: var(--sl-text-body-sm);
+			line-height: var(--sl-line-height-headings);
+		}
 	}
 </style>

package/components/ContentPanel.astro

@@ -3,23 +3,25 @@
 </div>
 
 <style>
-	.content-panel {
-		padding: 1.5rem var(--sl-content-pad-x);
-	}
-	.content-panel + .content-panel {
-		border-top: 1px solid var(--sl-color-hairline);
-	}
-	.sl-container {
-		max-width: var(--sl-content-width);
-	}
+	@layer starlight.core {
+		.content-panel {
+			padding: 1.5rem var(--sl-content-pad-x);
+		}
+		.content-panel + .content-panel {
+			border-top: 1px solid var(--sl-color-hairline);
+		}
+		.sl-container {
+			max-width: var(--sl-content-width);
+		}
 
-	.sl-container > :global(* + *) {
-		margin-top: 1.5rem;
-	}
+		.sl-container > :global(* + *) {
+			margin-top: 1.5rem;
+		}
 
-	@media (min-width: 72rem) {
-		.sl-container {
-			margin-inline: var(--sl-content-margin-inline, auto);
+		@media (min-width: 72rem) {
+			.sl-container {
+				margin-inline: var(--sl-content-margin-inline, auto);
+			}
 		}
 	}
 </style>

package/components/EditLink.astro

@@ -14,13 +14,15 @@ const { editUrl } = Astro.locals.starlightRoute;
 }
 
 <style>
-	a {
-		gap: 0.5rem;
-		align-items: center;
-		text-decoration: none;
-		color: var(--sl-color-gray-3);
-	}
-	a:hover {
-		color: var(--sl-color-white);
+	@layer starlight.core {
+		a {
+			gap: 0.5rem;
+			align-items: center;
+			text-decoration: none;
+			color: var(--sl-color-gray-3);
+		}
+		a:hover {
+			color: var(--sl-color-white);
+		}
 	}
 </style>

package/components/Footer.astro

@@ -23,34 +23,36 @@ import { Icon } from '../components';
 </footer>
 
 <style>
-	footer {
-		flex-direction: column;
-		gap: 1.5rem;
-	}
-	.meta {
-		gap: 0.75rem 3rem;
-		justify-content: space-between;
-		flex-wrap: wrap;
-		margin-top: 3rem;
-		font-size: var(--sl-text-sm);
-		color: var(--sl-color-gray-3);
-	}
-	.meta > :global(p:only-child) {
-		margin-inline-start: auto;
-	}
+	@layer starlight.core {
+		footer {
+			flex-direction: column;
+			gap: 1.5rem;
+		}
+		.meta {
+			gap: 0.75rem 3rem;
+			justify-content: space-between;
+			flex-wrap: wrap;
+			margin-top: 3rem;
+			font-size: var(--sl-text-sm);
+			color: var(--sl-color-gray-3);
+		}
+		.meta > :global(p:only-child) {
+			margin-inline-start: auto;
+		}
 
-	.kudos {
-		align-items: center;
-		gap: 0.5em;
-		margin: 1.5rem auto;
-		font-size: var(--sl-text-xs);
-		text-decoration: none;
-		color: var(--sl-color-gray-3);
-	}
-	.kudos :global(svg) {
-		color: var(--sl-color-orange);
-	}
-	.kudos:hover {
-		color: var(--sl-color-white);
+		.kudos {
+			align-items: center;
+			gap: 0.5em;
+			margin: 1.5rem auto;
+			font-size: var(--sl-text-xs);
+			text-decoration: none;
+			color: var(--sl-color-gray-3);
+		}
+		.kudos :global(svg) {
+			color: var(--sl-color-orange);
+		}
+		.kudos:hover {
+			color: var(--sl-color-white);
+		}
 	}
 </style>

package/components/Header.astro

@@ -14,7 +14,7 @@ const shouldRenderSearch =
 	config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
 ---
 
-<div class="header sl-flex">
+<div class="header">
 	<div class="title-wrapper sl-flex">
 		<SiteTitle />
 	</div>
@@ -31,61 +31,64 @@ const shouldRenderSearch =
 </div>
 
 <style>
-	.header {
-		gap: var(--sl-nav-gap);
-		justify-content: space-between;
-		align-items: center;
-		height: 100%;
-	}
-
-	.title-wrapper {
-		/* Prevent long titles overflowing and covering the search and menu buttons on narrow viewports. */
-		overflow: clip;
-		/* Avoid clipping focus ring around link inside title wrapper. */
-		padding: 0.25rem;
-		margin: -0.25rem;
-		min-width: 0;
-	}
+	@layer starlight.core {
+		.header {
+			display: flex;
+			gap: var(--sl-nav-gap);
+			justify-content: space-between;
+			align-items: center;
+			height: 100%;
+		}
 
-	.right-group,
-	.social-icons {
-		gap: 1rem;
-		align-items: center;
-	}
-	.social-icons::after {
-		content: '';
-		height: 2rem;
-		border-inline-end: 1px solid var(--sl-color-gray-5);
-	}
+		.title-wrapper {
+			/* Prevent long titles overflowing and covering the search and menu buttons on narrow viewports. */
+			overflow: clip;
+			/* Avoid clipping focus ring around link inside title wrapper. */
+			padding: 0.25rem;
+			margin: -0.25rem;
+			min-width: 0;
+		}
 
-	@media (min-width: 50rem) {
-		:global(:root[data-has-sidebar]) {
-			--__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+		.right-group,
+		.social-icons {
+			gap: 1rem;
+			align-items: center;
 		}
-		:global(:root:not([data-has-toc])) {
-			--__toc-width: 0rem;
+		.social-icons::after {
+			content: '';
+			height: 2rem;
+			border-inline-end: 1px solid var(--sl-color-gray-5);
 		}
-		.header {
-			--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
-			--__main-column-fr: calc(
-				(
-						100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
-							(2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
-							var(--sl-content-width)
-					) / 2
-			);
-			display: grid;
-			grid-template-columns:
+
+		@media (min-width: 50rem) {
+			:global(:root[data-has-sidebar]) {
+				--__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+			}
+			:global(:root:not([data-has-toc])) {
+				--__toc-width: 0rem;
+			}
+			.header {
+				--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
+				--__main-column-fr: calc(
+					(
+							100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
+								(2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
+								var(--sl-content-width)
+						) / 2
+				);
+				display: grid;
+				grid-template-columns:
         /* 1 (site title): runs up until the main content column’s left edge or the width of the title, whichever is the largest  */
-				minmax(
-					calc(var(--__sidebar-width) + max(0rem, var(--__main-column-fr) - var(--sl-nav-gap))),
-					auto
-				)
-				/* 2 (search box): all free space that is available. */
-				1fr
-				/* 3 (right items): use the space that these need. */
-				auto;
-			align-content: center;
+					minmax(
+						calc(var(--__sidebar-width) + max(0rem, var(--__main-column-fr) - var(--sl-nav-gap))),
+						auto
+					)
+					/* 2 (search box): all free space that is available. */
+					1fr
+					/* 3 (right items): use the space that these need. */
+					auto;
+				align-content: center;
+			}
 		}
 	}
 </style>

package/components/Hero.astro

@@ -64,78 +64,80 @@ if (image) {
 </div>
 
 <style>
-	.hero {
-		display: grid;
-		align-items: center;
-		gap: 1rem;
-		padding-bottom: 1rem;
-	}
-
-	.hero > img,
-	.hero > .hero-html {
-		object-fit: contain;
-		width: min(70%, 20rem);
-		height: auto;
-		margin-inline: auto;
-	}
-
-	.stack {
-		flex-direction: column;
-		gap: clamp(1.5rem, calc(1.5rem + 1vw), 2rem);
-		text-align: center;
-	}
-
-	.copy {
-		flex-direction: column;
-		gap: 1rem;
-		align-items: center;
-	}
-
-	.copy > * {
-		max-width: 50ch;
-	}
-
-	h1 {
-		font-size: clamp(var(--sl-text-3xl), calc(0.25rem + 5vw), var(--sl-text-6xl));
-		line-height: var(--sl-line-height-headings);
-		font-weight: 600;
-		color: var(--sl-color-white);
-	}
-
-	.tagline {
-		font-size: clamp(var(--sl-text-base), calc(0.0625rem + 2vw), var(--sl-text-xl));
-		color: var(--sl-color-gray-2);
-	}
-
-	.actions {
-		gap: 1rem 2rem;
-		flex-wrap: wrap;
-		justify-content: center;
-	}
-
-	@media (min-width: 50rem) {
+	@layer starlight.core {
 		.hero {
-			grid-template-columns: 7fr 4fr;
-			gap: 3%;
-			padding-block: clamp(2.5rem, calc(1rem + 10vmin), 10rem);
+			display: grid;
+			align-items: center;
+			gap: 1rem;
+			padding-bottom: 1rem;
 		}
 
 		.hero > img,
 		.hero > .hero-html {
-			order: 2;
-			width: min(100%, 25rem);
+			object-fit: contain;
+			width: min(70%, 20rem);
+			height: auto;
+			margin-inline: auto;
 		}
 
 		.stack {
-			text-align: start;
+			flex-direction: column;
+			gap: clamp(1.5rem, calc(1.5rem + 1vw), 2rem);
+			text-align: center;
 		}
 
 		.copy {
-			align-items: flex-start;
+			flex-direction: column;
+			gap: 1rem;
+			align-items: center;
+		}
+
+		.copy > * {
+			max-width: 50ch;
+		}
+
+		h1 {
+			font-size: clamp(var(--sl-text-3xl), calc(0.25rem + 5vw), var(--sl-text-6xl));
+			line-height: var(--sl-line-height-headings);
+			font-weight: 600;
+			color: var(--sl-color-white);
+		}
+
+		.tagline {
+			font-size: clamp(var(--sl-text-base), calc(0.0625rem + 2vw), var(--sl-text-xl));
+			color: var(--sl-color-gray-2);
 		}
 
 		.actions {
-			justify-content: flex-start;
+			gap: 1rem 2rem;
+			flex-wrap: wrap;
+			justify-content: center;
+		}
+
+		@media (min-width: 50rem) {
+			.hero {
+				grid-template-columns: 7fr 4fr;
+				gap: 3%;
+				padding-block: clamp(2.5rem, calc(1rem + 10vmin), 10rem);
+			}
+
+			.hero > img,
+			.hero > .hero-html {
+				order: 2;
+				width: min(100%, 25rem);
+			}
+
+			.stack {
+				text-align: start;
+			}
+
+			.copy {
+				align-items: flex-start;
+			}
+
+			.actions {
+				justify-content: flex-start;
+			}
 		}
 	}
 </style>

package/components/MobileMenuFooter.astro

@@ -5,7 +5,7 @@ import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
 ---
 
 <div class="mobile-preferences sl-flex">
-	<div class="sl-flex social-icons">
+	<div class="social-icons">
 		<SocialIcons />
 	</div>
 	<ThemeSelect />
@@ -13,20 +13,23 @@ import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
 </div>
 
 <style>
-	.social-icons {
-		margin-inline-end: auto;
-		gap: 1rem;
-		align-items: center;
-		padding-block: 1rem;
-	}
-	.social-icons:empty {
-		display: none;
-	}
-	.mobile-preferences {
-		justify-content: space-between;
-		flex-wrap: wrap;
-		border-top: 1px solid var(--sl-color-gray-6);
-		column-gap: 1rem;
-		padding: 0.5rem 0;
+	@layer starlight.core {
+		.social-icons {
+			display: flex;
+			margin-inline-end: auto;
+			gap: 1rem;
+			align-items: center;
+			padding-block: 1rem;
+		}
+		.social-icons:empty {
+			display: none;
+		}
+		.mobile-preferences {
+			justify-content: space-between;
+			flex-wrap: wrap;
+			border-top: 1px solid var(--sl-color-gray-6);
+			column-gap: 1rem;
+			padding: 0.5rem 0;
+		}
 	}
 </style>