@astrojs/starlight 0.39.3 → 0.41.0

package/integrations/remark-rehype.ts

@@ -1,25 +1,30 @@
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { AstroConfig } from 'astro';
-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 { resolveCollectionPath } from '../utils/collection-fs';
-import type { HookParameters, StarlightConfig } from '../types';
-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-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: RemarkRehypePluginOptions): RemarkPlugin[] {
+export function starlightRemarkPlugins(options: MarkdownProcessorPluginOptions): RemarkPlugin[] {
 	return [remarkDirective, remarkPlugins(options)];
 }
 
 /** List of rehype plugins to apply. */
-export function starlightRehypePlugins(options: RemarkRehypePluginOptions): RehypePlugin[] {
+export function starlightRehypePlugins(options: MarkdownProcessorPluginOptions): RehypePlugin[] {
 	return [
 		...(options.starlightConfig.markdown.headingLinks ? [[rehypeHeadingIds]] : []),
 		rehypePlugins(options),
@@ -27,8 +32,8 @@ export function starlightRehypePlugins(options: RemarkRehypePluginOptions): Rehy
 }
 
 /** Remark plugin applying other Starlight remark plugins if necessary. */
-function remarkPlugins(options: RemarkRehypePluginOptions): RemarkPlugin {
-	const remarkRehypePaths = getRemarkRehypePaths(options);
+function remarkPlugins(options: MarkdownProcessorPluginOptions): RemarkPlugin {
+	const allowedPaths = getMarkdownProcessorPaths(options);
 
 	return function attacher(this) {
 		const remarkAsidesTransformer = remarkAsides(options).call(this)!;
@@ -36,7 +41,7 @@ function remarkPlugins(options: RemarkRehypePluginOptions): RemarkPlugin {
 		return async function transformer(...args) {
 			const [, file] = args;
 
-			if (!shouldTransformFile(file, remarkRehypePaths)) return;
+			if (!shouldTransformFile(file, allowedPaths)) return;
 
 			await remarkAsidesTransformer(...args);
 		};
@@ -44,8 +49,8 @@ function remarkPlugins(options: RemarkRehypePluginOptions): RemarkPlugin {
 }
 
 /** Rehype plugin applying other Starlight rehype plugins if necessary. */
-function rehypePlugins(options: RemarkRehypePluginOptions): RehypePlugin {
-	const remarkRehypePaths = getRemarkRehypePaths(options);
+function rehypePlugins(options: MarkdownProcessorPluginOptions): RehypePlugin {
+	const allowedPaths = getMarkdownProcessorPaths(options);
 
 	return function attacher(this) {
 		const rehypeRtlCodeSupportTransformer = rehypeRtlCodeSupport(options).call(this);
@@ -54,7 +59,7 @@ function rehypePlugins(options: RemarkRehypePluginOptions): RehypePlugin {
 		return async function transformer(...args) {
 			const [, file] = args;
 
-			if (!shouldTransformFile(file, remarkRehypePaths)) return;
+			if (!shouldTransformFile(file, allowedPaths)) return;
 
 			await rehypeRtlCodeSupportTransformer(...args);
 
@@ -65,52 +70,17 @@ function rehypePlugins(options: RemarkRehypePluginOptions): RehypePlugin {
 	};
 }
 
-/**
- * Returns the paths to the Starlight docs collection and any additional paths defined in the
- * `starlightConfig.markdown.processedDirs` option that can be used with the
- * `shouldTransformFile()` utility to determine if a file should be transformed by a plugin or not.
- */
-function getRemarkRehypePaths(options: RemarkRehypePluginOptions): string[] {
-	const paths = [normalizePath(resolveCollectionPath('docs', options.astroConfig.srcDir))];
-
-	for (const processedDir of options.starlightConfig.markdown.processedDirs) {
-		paths.push(normalizePath(resolve(fileURLToPath(options.astroConfig.root), processedDir)));
-	}
-
-	return paths;
-}
-
 /**
  * Determines if a file should be transformed by a remark/rehype plugin, e.g. files without a known
- * path or files that are not part of the allowed remark/rehype paths are skipped.
+ * path or files that are not part of the allowed paths are skipped.
  */
-function shouldTransformFile(file: VFile, remarkRehypePaths: string[]) {
+function shouldTransformFile(file: VFile, allowedPaths: string[]) {
 	// If the content is rendered using the content loader `renderMarkdown()` API, a file path
 	// is not provided.
 	// In that case, we skip the file.
 	if (!file?.path) return false;
 
-	const normalizedPath = normalizePath(file.path);
-
-	// If the document is not part of the allowed remark/rehype paths, skip it.
-	return remarkRehypePaths.some((path) => normalizedPath.startsWith(path));
-}
-
-/**
- * File path separators seems to be inconsistent on Windows between remark/rehype plugins used on
- * Markdown vs MDX files.
- * For the time being, we normalize all paths to unix style paths.
- */
-const backSlashRegex = /\\/g;
-function normalizePath(path: string) {
-	return path.replace(backSlashRegex, '/');
-}
-
-export interface RemarkRehypePluginOptions {
-	starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales' | 'markdown'>;
-	astroConfig: Pick<AstroConfig, 'root' | 'srcDir'>;
-	useTranslations: HookParameters<'config:setup'>['useTranslations'];
-	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang'];
+	return shouldTransformPath(file.path, allowedPaths);
 }
 
 type RemarkPlugin = Plugin<[], RemarkRoot>;

package/integrations/satteri.ts

@@ -0,0 +1,288 @@
+import { fileURLToPath } from 'node:url';
+import { satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri';
+import type { Element, Properties } from 'hast';
+import type { Paragraph } from 'mdast';
+import { directiveToMarkdown } from 'mdast-util-directive';
+import { toMarkdown } from 'mdast-util-to-markdown';
+import type {
+	HastPluginDefinition,
+	HastPluginInput,
+	MdastPluginInput,
+	MdastPluginDefinition,
+} from 'satteri';
+import { anchorLinkIconPath } from './anchor-icon';
+import { asideIconPathAttrs, isAsideVariant } from './aside-icons';
+import {
+	getMarkdownProcessorPaths,
+	shouldTransformPath,
+	type MarkdownProcessorPluginOptions,
+} from './markdown-processor';
+import { Icons } from '../components-internals/Icons';
+import { throwInvalidAsideIconError } from './asides-error';
+import type { StarlightIcon } from '../types';
+
+export function starlightSatteriPlugins(options: MarkdownProcessorPluginOptions): {
+	mdastPlugins: MdastPluginInput[];
+	hastPlugins: HastPluginInput[];
+} {
+	const allowedPaths = getMarkdownProcessorPaths(options);
+	return {
+		mdastPlugins: [satteriAsidesPlugin(options, allowedPaths)],
+		hastPlugins: [
+			satteriRtlCodeSupportPlugin(allowedPaths),
+			...(options.starlightConfig.markdown.headingLinks
+				? [() => satteriHeadingIdsPlugin(), satteriAutolinkHeadingsPlugin(options, allowedPaths)]
+				: []),
+		],
+	};
+}
+
+/**
+ * Recover directives Starlight didn't claim so user content isn't dropped
+ */
+export function satteriDirectivesRestoration(): MdastPluginDefinition {
+	return {
+		name: 'starlight-directives-restoration',
+		textDirective(node) {
+			// Leave directives another plugin already handled (i.e. set `data` on) untouched.
+			if (node.data !== undefined) return;
+			return { type: 'text', value: serializeDirective(node) };
+		},
+		leafDirective(node) {
+			if (node.data !== undefined) return;
+			return {
+				type: 'paragraph',
+				children: [{ type: 'text', value: serializeDirective(node) }],
+			};
+		},
+		containerDirective(node) {
+			if (node.data !== undefined) return;
+			return paragraphElement('div', {}, [...node.children]);
+		},
+	};
+}
+
+function paragraphElement(
+	tagName: string,
+	properties: Properties,
+	children: unknown[] = []
+): Paragraph {
+	return {
+		type: 'paragraph',
+		data: { hName: tagName, hProperties: properties },
+		children: children as Paragraph['children'],
+	};
+}
+
+/** Convert `:::variant` directive blocks into styled asides. */
+function satteriAsidesPlugin(
+	options: MarkdownProcessorPluginOptions,
+	allowedPaths: string[]
+): MdastPluginDefinition {
+	return {
+		name: 'starlight-asides',
+		containerDirective(node, ctx) {
+			if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return;
+			if (!isAsideVariant(node.name)) return;
+
+			const variant = node.name;
+			// `shouldTransformPath` above already returned for a missing `fileURL`.
+			const filename = fileURLToPath(ctx.fileURL!);
+			const t = options.useTranslations(options.absolutePathToLang(filename));
+
+			let title = t(`aside.${variant}`);
+			let titleNode: unknown[] = [{ type: 'text', value: title }];
+			const children = [...node.children];
+			const firstChild = children[0];
+			if (
+				firstChild?.type === 'paragraph' &&
+				firstChild.data?.directiveLabel &&
+				firstChild.children.length > 0
+			) {
+				titleNode = firstChild.children;
+				title = ctx.textContent(firstChild);
+				children.shift();
+			}
+
+			const customIconName = node.attributes?.['icon'];
+			let innerSvgHtml: string;
+			if (customIconName) {
+				const icon = Icons[customIconName as StarlightIcon];
+				if (!icon) throwInvalidAsideIconError(customIconName);
+				innerSvgHtml = icon;
+			} else {
+				innerSvgHtml = asideIconPathAttrs[variant]
+					.map((attrs) => `<path${attrsToHtml(attrs)}/>`)
+					.join('');
+			}
+			const iconSvg = `<svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon">${innerSvgHtml}</svg>`;
+
+			return paragraphElement(
+				'aside',
+				{
+					'aria-label': title,
+					class: `starlight-aside starlight-aside--${variant}`,
+				},
+				[
+					paragraphElement('p', { class: 'starlight-aside__title', 'aria-hidden': 'true' }, [
+						{ type: 'html', value: iconSvg },
+						...titleNode,
+					]),
+					paragraphElement('div', { class: 'starlight-aside__content' }, children),
+				]
+			);
+		},
+	};
+}
+
+function attrsToHtml(attrs: Record<string, string>): string {
+	let out = '';
+	for (const [key, value] of Object.entries(attrs)) {
+		out += ` ${key}="${value.replace(/&/g, '&amp;').replace(/"/g, '&quot;')}"`;
+	}
+	return out;
+}
+
+function serializeDirective(node: Parameters<typeof toMarkdown>[0]): string {
+	const md = toMarkdown(node, { extensions: [directiveToMarkdown()] });
+	return md.at(-1) === '\n' ? md.slice(0, -1) : md;
+}
+
+function satteriRtlCodeSupportPlugin(allowedPaths: string[]): () => HastPluginDefinition {
+	return () => {
+		// HACK: Sätteri currently does not expose a way to either know the parent of a node, or
+		// skipping a subtree visit. To work around this, we manually track the source spans of `<pre>`
+		// elements and skip applying `dir="auto"` to `<code>` elements inside those spans. This is:
+		// bad, because it means that it won't work for nodes without positions (e.g. generated nodes),
+		// but it's as good as it gets right now.
+		const preSpans: Array<[number, number]> = [];
+		return {
+			name: 'starlight-rtl-code-support',
+			element: [
+				{
+					filter: ['pre'],
+					visit(node, ctx) {
+						if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return;
+						const span = nodeSpan(node);
+						if (span) preSpans.push(span);
+						if (node.properties && 'dir' in node.properties) return;
+						ctx.setProperty(node, 'dir', 'ltr');
+					},
+				},
+				{
+					filter: ['code'],
+					visit(node, ctx) {
+						if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return;
+						if (isInsideSpan(nodeSpan(node), preSpans)) return;
+						if (node.properties && 'dir' in node.properties) return;
+						ctx.setProperty(node, 'dir', 'auto');
+					},
+				},
+			],
+			// Shiki runs ahead of us and replaces the highlighted `<pre>` element with a raw HTML
+			// node, so the `pre` element visitor above never sees it. Patch the raw markup instead.
+			raw(node, ctx) {
+				if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return undefined;
+				const value = ltrRawPre(node.value);
+				if (value === null) return undefined;
+				return { type: 'raw', value };
+			},
+		};
+	};
+}
+
+/** The source byte span of a node, or `null` when it carries no position (e.g. a generated node). */
+function nodeSpan(node: { position?: Element['position'] }): [number, number] | null {
+	const start = node.position?.start.offset;
+	const end = node.position?.end.offset;
+	return typeof start === 'number' && typeof end === 'number' ? [start, end] : null;
+}
+
+function isInsideSpan(span: [number, number] | null, spans: Array<[number, number]>): boolean {
+	if (!span) return false;
+	return spans.some(([start, end]) => span[0] >= start && span[1] <= end);
+}
+
+const rawPreOpenTag = /<pre(?=[\s>])[^>]*>/;
+
+/**
+ * Add `dir="ltr"` to the opening tag of a raw `<pre>` HTML string, unless it already declares a
+ * `dir`. Returns `null` when the value isn’t a `<pre>`, leaving unrelated raw HTML untouched.
+ */
+function ltrRawPre(value: string): string | null {
+	const openTag = value.match(rawPreOpenTag)?.[0];
+	if (!openTag || /\sdir\s*=/.test(openTag)) return null;
+	return value.replace(openTag, () => `<pre dir="ltr"${openTag.slice(4)}`);
+}
+
+function satteriAutolinkHeadingsPlugin(
+	options: MarkdownProcessorPluginOptions,
+	allowedPaths: string[]
+): HastPluginDefinition {
+	return {
+		name: 'starlight-autolink-headings',
+		element: {
+			filter: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+			visit(node, ctx) {
+				if (!shouldTransformPath(ctx.fileURL, allowedPaths)) return;
+
+				const id = node.properties?.['id'];
+				if (typeof id !== 'string' || !id) return;
+
+				const title = ctx.textContent(node);
+				// `shouldTransformPath` above already returned for a missing `fileURL`.
+				const filename = fileURLToPath(ctx.fileURL!);
+				const t = options.useTranslations(options.absolutePathToLang(filename));
+				const accessibleLabel = t('heading.anchorLabel', {
+					title,
+					interpolation: { escapeValue: false },
+				});
+
+				return {
+					type: 'element',
+					tagName: 'div',
+					properties: { class: `sl-heading-wrapper level-${node.tagName}` },
+					children: [
+						node,
+						{
+							type: 'element',
+							tagName: 'a',
+							properties: { class: 'sl-anchor-link', href: '#' + id },
+							children: [
+								{
+									type: 'element',
+									tagName: 'span',
+									properties: { 'aria-hidden': 'true', class: 'sl-anchor-icon' },
+									children: [
+										{
+											type: 'element',
+											tagName: 'svg',
+											properties: { width: '16', height: '16', viewBox: '0 0 24 24' },
+											children: [
+												{
+													type: 'element',
+													tagName: 'path',
+													properties: {
+														fill: 'currentcolor',
+														d: anchorLinkIconPath,
+													},
+													children: [],
+												},
+											],
+										},
+									],
+								},
+								{
+									type: 'element',
+									tagName: 'span',
+									properties: { class: 'sr-only', 'data-pagefind-ignore': true },
+									children: [{ type: 'text', value: accessibleLabel }],
+								},
+							],
+						},
+					],
+				};
+			},
+		},
+	};
+}

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.39.3",
+  "version": "0.41.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -42,25 +42,32 @@
     "./style/markdown.css": "./style/markdown.css"
   },
   "peerDependencies": {
-    "astro": "^6.0.0"
+    "@astrojs/markdown-remark": "^7.2.0",
+    "astro": "^7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@astrojs/markdown-remark": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@astrojs/markdown-remark": "^7.2.0",
     "@playwright/test": "^1.59.1",
     "@types/node": "^22.19.17",
     "@vitest/coverage-v8": "^4.1.5",
-    "astro": "^6.3.1",
+    "astro": "^7.0.2",
     "linkedom": "^0.18.12",
     "vitest": "^4.1.5"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.1.1",
-    "@astrojs/mdx": "^5.0.4",
+    "@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",
     "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
-    "astro-expressive-code": "^0.42.0",
+    "astro-expressive-code": "^0.43.1",
     "bcp-47": "^2.1.0",
     "hast-util-from-html": "^2.0.3",
     "hast-util-select": "^6.0.4",
@@ -77,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 {