@astrojs/starlight 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @astrojs/starlight
 
+## 0.41.0
+
+### Minor Changes
+
+- [#3951](https://github.com/withastro/starlight/pull/3951) [`1202dd4`](https://github.com/withastro/starlight/commit/1202dd4c3efd517bdfe213eaf84262e439485e45) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Astro v7, drops support for Astro v6.
+
+  #### Upgrade Astro and dependencies
+
+  ⚠️ **BREAKING CHANGE:** Astro v6 is no longer supported. Make sure you [update Astro](https://docs.astro.build/en/guides/upgrade-to/v7/) and any other official integrations at the same time as updating Starlight:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+  _Community Starlight plugins and Astro integrations may also need to be manually updated to work with Astro v7. If you encounter any issues, please reach out to the plugin or integration author to see if it is a known issue or if an updated version is being worked on._
+
+  ⚠️ **BREAKING CHANGE:** This release drops official support for Chromium-based browsers prior to version 111 (released 07 March 2023) and Safari-based browsers prior to version 16.4 (released 27 March 2023). You can find a list of currently supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+111%2C+Edge+%3E%3D+111%2C+Firefox+%3E%3D+121%2C+Safari+%3E%3D+16.4%2C+iOS+%3E%3D+16.4%2C+not+op_mini+all).
+
+### Patch Changes
+
+- [#3953](https://github.com/withastro/starlight/pull/3953) [`a935d33`](https://github.com/withastro/starlight/commit/a935d334c193fb452f72453ea1bf38807d415077) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes Starlight Markdown processing being potentially applied to files that should not be processed.
+
 ## 0.40.0
 
 ### Minor Changes

package/index.ts

@@ -10,17 +10,18 @@
 import mdx from '@astrojs/mdx';
 import type { AstroIntegration } from 'astro';
 import { AstroError } from 'astro/errors';
-import type { MarkdownProcessorPluginOptions } from './integrations/markdown-process';
+import type { MarkdownProcessorPluginOptions } from './integrations/markdown-processor';
 import {
 	applyStarlightMarkdownPlugins,
-	satteriIntegration,
 	starlightDirectivesRestorationIntegration,
+	unifiedIntegration,
 } from './integrations/markdown-plugins';
 import { starlightExpressiveCode } from './integrations/expressive-code/index';
 import { starlightPagefind } from './integrations/pagefind';
 import { starlightSitemap } from './integrations/sitemap';
 import { vitePluginStarlightCssLayerOrder } from './integrations/vite-layer-order';
-import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
+import { vitePluginStarlightLazyBarrelOptimization } from './integrations/vite-lazy-barrel-optimization';
+import { vitePluginStarlightVirtualModules } from './integrations/vite-virtual-modules';
 import {
 	injectPluginTranslationsTypes,
 	runPlugins,
@@ -90,11 +91,10 @@ export default function StarlightIntegration(
 					prerender: starlightConfig.prerender,
 				});
 
-				// Astro 6.4+ always sets `config.markdown.processor` (defaulting to `unified()`). Resolve
-				// it and the optional Sätteri integration up front so we can reject unsupported
-				// usage before wiring up the integrations below.
+				// Resolve the configured processor and the optional Unified integration up front before
+				// wiring up the integrations below.
 				const processor = config.markdown.processor;
-				const satteri = await satteriIntegration;
+				const unified = await unifiedIntegration;
 
 				// Add built-in integrations only if they are not already added by the user through the
 				// config or by a plugin.
@@ -119,7 +119,7 @@ export default function StarlightIntegration(
 				};
 
 				// We push our plugins onto the processor's options.
-				applyStarlightMarkdownPlugins(processor, markdownProcessorOptions, satteri, logger);
+				applyStarlightMarkdownPlugins(processor, markdownProcessorOptions, unified, logger);
 
 				// Add Starlight directives restoration integration at the end of the list so that
 				// remark/mdast plugins injected by Starlight plugins through Astro integrations can
@@ -145,7 +145,8 @@ export default function StarlightIntegration(
 					vite: {
 						plugins: [
 							vitePluginStarlightCssLayerOrder(),
-							vitePluginStarlightUserConfig(
+							vitePluginStarlightLazyBarrelOptimization(),
+							vitePluginStarlightVirtualModules(
 								{ command, isNodeCompatibleEnv },
 								starlightConfig,
 								config,

package/integrations/anchor-icon.ts

@@ -1,5 +1,5 @@
 // SVG `d` for the anchor-link icon rendered next to headings. Shared by the unified
-// (`heading-links.ts`) and Sätteri (`satteri.ts`) autolink plugins and the `<AnchorHeading>`
-// component so the three stay in sync.
+// (`rehype-heading-links.ts`) and Sätteri (`satteri.ts`) autolink plugins and the
+// `<AnchorHeading>` component so the three stay in sync.
 export const anchorLinkIconPath =
 	'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';

package/integrations/markdown-plugins.ts

@@ -1,53 +1,56 @@
-import { isUnifiedProcessor } from '@astrojs/markdown-remark';
+import { isSatteriProcessor } from '@astrojs/markdown-satteri';
 import type { AstroConfig, AstroIntegration, AstroIntegrationLogger } from 'astro';
-import { remarkDirectivesRestoration } from './asides';
-import type { MarkdownProcessorPluginOptions } from './markdown-process';
-import { starlightRehypePlugins, starlightRemarkPlugins } from './remark-rehype';
+import type { MarkdownProcessorPluginOptions } from './markdown-processor';
+import { satteriDirectivesRestoration, starlightSatteriPlugins } from './satteri';
 
-// For some reason, trying to `await import("./satteri")` in the integration module causes a Vite
-// error about the module runner being closed. This shape works, not sure why!
-export const satteriIntegration = import('./satteri').catch(() => null);
+// This file is imported by the Starlight integration that is used in Astro configuration files.
+// When using Starlight, Astro loads its configuration using a temporary Vite module runner and
+// closes it before running integration hooks. If this dynamic import is started later from an
+// integration hook, Vite tries to resolve it through that closed runner and throw "Vite module
+// runner has been closed".
+// We start loading `./remark-rehype` at the top level so Vite waits for it to resolve or fail
+// while the config runner is still running. This keeps the Unified integration optional as when
+// `@astrojs/markdown-remark` is not installed, importing `./remark-rehype` rejects and we resolve
+// it to `null`, which is later used to detect if Unified support is available or not.
+export const unifiedIntegration = import('./remark-rehype').catch(() => null);
 
-type SatteriIntegration = Awaited<typeof satteriIntegration>;
+type UnifiedIntegration = Awaited<typeof unifiedIntegration>;
 type MarkdownProcessor = NonNullable<AstroConfig['markdown']['processor']>;
 
-/**
- * Registers Starlight's Markdown transforms on the Astro 6.4+ `markdown.processor`, picking the
- * plugin set for the configured engine.
- */
+/** Registers Starlight's Markdown transforms, picking the plugin set for the configured engine. */
 export function applyStarlightMarkdownPlugins(
 	processor: MarkdownProcessor,
 	options: MarkdownProcessorPluginOptions,
-	satteri: SatteriIntegration,
+	unified: UnifiedIntegration,
 	logger: Pick<AstroIntegrationLogger, 'warn'>
 ) {
-	if (satteri?.isSatteriProcessor(processor)) {
+	if (isSatteriProcessor(processor)) {
 		// Starlight's asides are built on container directives, which Sätteri disables by default.
 		processor.options.features.directive = true;
-		const { mdastPlugins, hastPlugins } = satteri.starlightSatteriPlugins(options);
+		const { mdastPlugins, hastPlugins } = starlightSatteriPlugins(options);
 		processor.options.mdastPlugins.push(...mdastPlugins);
 		processor.options.hastPlugins.push(...hastPlugins);
-	} else if (isUnifiedProcessor(processor)) {
-		processor.options.remarkPlugins.push(...starlightRemarkPlugins(options));
-		processor.options.rehypePlugins.push(...starlightRehypePlugins(options));
+	} else if (unified?.isUnifiedProcessor(processor)) {
+		processor.options.remarkPlugins.push(...unified.starlightRemarkPlugins(options));
+		processor.options.rehypePlugins.push(...unified.starlightRehypePlugins(options));
 	} else {
 		logger.warn(
 			`The configured \`markdown.processor\` ("${processor.name}") is not supported by Starlight. ` +
 				"Starlight's Markdown transforms (asides, heading anchor links, RTL code support) won't run on your content. " +
-				'Switch to `unified()` from `@astrojs/markdown-remark` or `satteri()` from `@astrojs/markdown-satteri`.'
+				'Switch to `satteri()` from `@astrojs/markdown-satteri` or `unified()` from `@astrojs/markdown-remark`.'
 		);
 	}
 }
 
-/** Registers the directive-restoration plugin on the Astro 6.4+ `markdown.processor`. */
+/** Registers the directive-restoration plugin. */
 export function registerDirectivesRestoration(
 	processor: MarkdownProcessor,
-	satteri: SatteriIntegration
+	unified: UnifiedIntegration
 ) {
-	if (satteri?.isSatteriProcessor(processor)) {
-		processor.options.mdastPlugins.push(satteri.satteriDirectivesRestoration());
-	} else if (isUnifiedProcessor(processor)) {
-		processor.options.remarkPlugins.push(remarkDirectivesRestoration);
+	if (isSatteriProcessor(processor)) {
+		processor.options.mdastPlugins.push(satteriDirectivesRestoration());
+	} else if (unified?.isUnifiedProcessor(processor)) {
+		processor.options.remarkPlugins.push(unified.remarkDirectivesRestoration);
 	}
 }
 
@@ -60,8 +63,8 @@ export function starlightDirectivesRestorationIntegration(): AstroIntegration {
 		name: 'starlight-directives-restoration',
 		hooks: {
 			'astro:config:setup': async ({ config }) => {
-				const satteri = await satteriIntegration;
-				registerDirectivesRestoration(config.markdown?.processor, satteri);
+				const unified = await unifiedIntegration;
+				registerDirectivesRestoration(config.markdown?.processor, unified);
 			},
 		},
 	};

package/integrations/{markdown-process.ts → markdown-processor.ts}

@@ -2,6 +2,7 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { AstroConfig } from 'astro';
 import { resolveCollectionPath } from '../utils/collection-fs';
+import { ensureTrailingSlash } from '../utils/path';
 import type { HookParameters, StarlightConfig } from '../types';
 
 /**
@@ -21,10 +22,12 @@ export interface MarkdownProcessorPluginOptions {
  * utility to determine if a file should be transformed by a plugin or not.
  */
 export function getMarkdownProcessorPaths(options: MarkdownProcessorPluginOptions): string[] {
-	const paths = [normalizePath(resolveCollectionPath('docs', options.astroConfig.srcDir))];
+	const paths = [normalizeDirectoryPath(resolveCollectionPath('docs', options.astroConfig.srcDir))];
 
 	for (const processedDir of options.starlightConfig.markdown.processedDirs) {
-		paths.push(normalizePath(resolve(fileURLToPath(options.astroConfig.root), processedDir)));
+		paths.push(
+			normalizeDirectoryPath(resolve(fileURLToPath(options.astroConfig.root), processedDir))
+		);
 	}
 
 	return paths;
@@ -50,3 +53,12 @@ const backSlashRegex = /\\/g;
 function normalizePath(path: string) {
 	return path.replace(backSlashRegex, '/');
 }
+
+/**
+ * Allowed paths are directory prefixes compared with `startsWith()` in {@link shouldTransformPath},
+ * so we ensure they have a trailing slash to avoid matching sibling directories with the same
+ * prefix.
+ */
+function normalizeDirectoryPath(path: string) {
+	return ensureTrailingSlash(normalizePath(path));
+}

package/integrations/{code-rtl-support.ts → rehype-code-rtl-support.ts}

@@ -1,7 +1,7 @@
 import type { Root } from 'hast';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
 import type { Transformer } from 'unified';
-import type { MarkdownProcessorPluginOptions } from './markdown-process';
+import type { MarkdownProcessorPluginOptions } from './markdown-processor';
 
 /**
  * rehype plugin that adds `dir` attributes to `<code>` and `<pre>`

package/integrations/{heading-links.ts → rehype-heading-links.ts}

@@ -4,7 +4,7 @@ import { h } from 'hastscript';
 import type { Transformer } from 'unified';
 import { SKIP, visit } from 'unist-util-visit';
 import { anchorLinkIconPath } from './anchor-icon';
-import type { MarkdownProcessorPluginOptions } from './markdown-process';
+import type { MarkdownProcessorPluginOptions } from './markdown-processor';
 
 const AnchorLinkIcon = h(
 	'span',

package/integrations/{asides.ts → remark-asides.ts}

@@ -12,7 +12,7 @@ import { toMarkdown } from 'mdast-util-to-markdown';
 import { toString } from 'mdast-util-to-string';
 import type { Plugin, Transformer } from 'unified';
 import { visit } from 'unist-util-visit';
-import type { MarkdownProcessorPluginOptions } from './markdown-process';
+import type { MarkdownProcessorPluginOptions } from './markdown-processor';
 import type { StarlightIcon } from '../types';
 import { Icons } from '../components-internals/Icons';
 import { fromHtml } from 'hast-util-from-html';

package/integrations/remark-rehype.ts

@@ -1,17 +1,22 @@
-import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import { isUnifiedProcessor, rehypeHeadingIds } from '@astrojs/markdown-remark';
 import type { Root as RehypeRoot } from 'hast';
 import type { Root as RemarkRoot } from 'mdast';
 import remarkDirective from 'remark-directive';
 import type { Plugin } from 'unified';
 import type { VFile } from 'vfile';
-import { remarkAsides } from './asides';
-import { rehypeRtlCodeSupport } from './code-rtl-support';
-import rehypeAutolinkHeadings from './heading-links';
+import { remarkAsides, remarkDirectivesRestoration } from './remark-asides';
+import { rehypeRtlCodeSupport } from './rehype-code-rtl-support';
+import rehypeAutolinkHeadings from './rehype-heading-links';
 import {
 	getMarkdownProcessorPaths,
 	shouldTransformPath,
 	type MarkdownProcessorPluginOptions,
-} from './markdown-process';
+} from './markdown-processor';
+
+// Re-exported so callers can narrow `markdown.processor` to the Unified processor and use the
+// remark directive-restoration plugin through the same lazy import that loads the optional
+// `@astrojs/markdown-remark` peer dependency.
+export { isUnifiedProcessor, remarkDirectivesRestoration };
 
 /** List of remark plugins to apply. */
 export function starlightRemarkPlugins(options: MarkdownProcessorPluginOptions): RemarkPlugin[] {

package/integrations/satteri.ts

@@ -1,5 +1,5 @@
 import { fileURLToPath } from 'node:url';
-import { isSatteriProcessor, satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri';
+import { satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri';
 import type { Element, Properties } from 'hast';
 import type { Paragraph } from 'mdast';
 import { directiveToMarkdown } from 'mdast-util-directive';
@@ -16,15 +16,11 @@ import {
 	getMarkdownProcessorPaths,
 	shouldTransformPath,
 	type MarkdownProcessorPluginOptions,
-} from './markdown-process';
+} from './markdown-processor';
 import { Icons } from '../components-internals/Icons';
 import { throwInvalidAsideIconError } from './asides-error';
 import type { StarlightIcon } from '../types';
 
-// Re-exported so callers can narrow `markdown.processor` to a Sätteri processor through the same
-// lazy import that loads the optional `@astrojs/markdown-satteri` peer dependency.
-export { isSatteriProcessor };
-
 export function starlightSatteriPlugins(options: MarkdownProcessorPluginOptions): {
 	mdastPlugins: MdastPluginInput[];
 	hastPlugins: HastPluginInput[];

package/integrations/vite-lazy-barrel-optimization.ts

@@ -0,0 +1,40 @@
+import { fileURLToPath } from 'node:url';
+import type { ViteUserConfig } from 'astro';
+
+// https://vite.dev/guide/api-plugin#hook-filters
+const componentsBarrelIdFilter = /[\\/]components\.ts(?:\?.*)?$/;
+
+const backSlashRegex = /\\/g;
+const queryStringRegex = /\?.*$/;
+
+const starlightComponentsBarrelId = normalizeId(
+	fileURLToPath(new URL('../components.ts', import.meta.url))
+);
+
+/**
+ * Vite plugin that marks the Starlight components barrel file as having no side effects so that
+ * lazy barrel optimization can be applied to it.
+ *
+ * @see https://rolldown.rs/in-depth/lazy-barrel-optimization
+ */
+export function vitePluginStarlightLazyBarrelOptimization(): VitePlugin {
+	return {
+		name: 'vite-plugin-starlight-lazy-barrel-optimization',
+		enforce: 'pre',
+		transform: {
+			filter: {
+				id: componentsBarrelIdFilter,
+			},
+			handler(code, id) {
+				if (normalizeId(id) !== starlightComponentsBarrelId) return;
+				return { code, moduleSideEffects: false };
+			},
+		},
+	};
+}
+
+function normalizeId(id: string) {
+	return id.replace(backSlashRegex, '/').replace(queryStringRegex, '');
+}
+
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];

package/integrations/{virtual-user-config.ts → vite-virtual-modules.ts}

@@ -17,7 +17,7 @@ function resolveVirtualModuleId<T extends string>(id: T): `\0${T}` {
 }
 
 /** Vite plugin that exposes Starlight user config and project context via virtual modules. */
-export function vitePluginStarlightUserConfig(
+export function vitePluginStarlightVirtualModules(
 	{
 		command,
 		isNodeCompatibleEnv,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -42,27 +42,26 @@
     "./style/markdown.css": "./style/markdown.css"
   },
   "peerDependencies": {
-    "@astrojs/markdown-satteri": "^0.2.0",
-    "astro": "^6.4.5"
+    "@astrojs/markdown-remark": "^7.2.0",
+    "astro": "^7.0.2"
   },
   "peerDependenciesMeta": {
-    "@astrojs/markdown-satteri": {
+    "@astrojs/markdown-remark": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@astrojs/markdown-satteri": "^0.2.2",
+    "@astrojs/markdown-remark": "^7.2.0",
     "@playwright/test": "^1.59.1",
     "@types/node": "^22.19.17",
     "@vitest/coverage-v8": "^4.1.5",
-    "astro": "^6.4.5",
+    "astro": "^7.0.2",
     "linkedom": "^0.18.12",
-    "satteri": "^0.8.1",
     "vitest": "^4.1.5"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.2.0",
-    "@astrojs/mdx": "^6.0.2",
+    "@astrojs/markdown-satteri": "^0.3.2",
+    "@astrojs/mdx": "^7.0.0",
     "@astrojs/sitemap": "^3.7.2",
     "@pagefind/default-ui": "^1.3.0",
     "@types/hast": "^3.0.4",
@@ -85,6 +84,7 @@
     "rehype": "^13.0.2",
     "rehype-format": "^5.0.1",
     "remark-directive": "^4.0.0",
+    "satteri": "^0.9.1",
     "ultrahtml": "^1.6.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",

package/user-components/Badge.astro

@@ -16,14 +16,9 @@ const {
 	Astro.props,
 	'Invalid prop passed to the `<Badge/>` component.'
 );
-
-/**
- * The fragment around the element is used as a workaround to avoid a trailing whitespace in the output.
- * @see https://github.com/withastro/compiler/issues/1003
- */
 ---
 
-<><span class:list={['sl-badge', variant, size, customClass]} {...attrs}>{text}</span></>
+<span class:list={['sl-badge', variant, size, customClass]} {...attrs}>{text}</span>
 
 <style>
 	@layer starlight.components {

package/user-components/Icon.astro

@@ -11,24 +11,17 @@ interface Props {
 
 const { name, label, size = '1em', color } = Astro.props;
 const a11yAttrs = label ? ({ 'aria-label': label } as const) : ({ 'aria-hidden': 'true' } as const);
-
-/**
- * The fragment around the element is used as a workaround to avoid a trailing whitespace in the output.
- * @see https://github.com/withastro/compiler/issues/1003
- */
 ---
 
-<>
-	<svg
-		{...a11yAttrs}
-		class={Astro.props.class}
-		width="16"
-		height="16"
-		viewBox="0 0 24 24"
-		fill="currentColor"
-		set:html={Icons[name]}
-	/>
-</>
+<svg
+	{...a11yAttrs}
+	class={Astro.props.class}
+	width="16"
+	height="16"
+	viewBox="0 0 24 24"
+	fill="currentColor"
+	set:html={Icons[name]}
+/>
 
 <style define:vars={{ 'sl-icon-color': color, 'sl-icon-size': size }}>
 	@layer starlight.components {