@astrojs/starlight 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @astrojs/starlight
 
+## 0.17.1
+
+### Patch Changes
+
+- [#1437](https://github.com/withastro/starlight/pull/1437) [`655aed4`](https://github.com/withastro/starlight/commit/655aed4840cae59e9abd64b4b585e60f1cfab209) Thanks [@hippotastic](https://github.com/hippotastic)! - Adds Starlight-specific types to `defineEcConfig` function and exports `StarlightExpressiveCodeOptions`.
+
+  This provides Starlight types and IntelliSense support for your Expressive Code configuration options inside an `ec.config.mjs` file. See the [Expressive Code documentation](https://expressive-code.com/key-features/code-component/#using-an-ecconfigmjs-file) for more information.
+
+- [#1420](https://github.com/withastro/starlight/pull/1420) [`275f87f`](https://github.com/withastro/starlight/commit/275f87fd7fc676b9ab323354078c06894e0832c7) Thanks [@abdelhalimjean](https://github.com/abdelhalimjean)! - Fix rare `font-family` issue if users have a font installed with a name of `""`
+
+- [#1365](https://github.com/withastro/starlight/pull/1365) [`a0af7cc`](https://github.com/withastro/starlight/commit/a0af7cc696da987a76edab96cdd2329779e87724) Thanks [@kevinzunigacuellar](https://github.com/kevinzunigacuellar)! - Correctly format Pagefind search result links when `trailingSlash: 'never'` is used
+
+## 0.17.0
+
+### Minor Changes
+
+- [#1389](https://github.com/withastro/starlight/pull/1389) [`21b3620`](https://github.com/withastro/starlight/commit/21b36201aa1e01c8395d0f24b2fa4e32b90550bb) Thanks [@connor-baer](https://github.com/connor-baer)! - Adds new `disable404Route` config option to disable injection of Astro’s default 404 route
+
+- [#1395](https://github.com/withastro/starlight/pull/1395) [`ce05dfb`](https://github.com/withastro/starlight/commit/ce05dfb4b1e9b90fad057d5d4328e4445f986b3b) Thanks [@hippotastic](https://github.com/hippotastic)! - Adds a new [`<Code>` component](https://starlight.astro.build/guides/components/#code) to render dynamic code strings with Expressive Code
+
 ## 0.16.0
 
 ### Minor Changes

package/components/Search.astro

@@ -1,6 +1,7 @@
 ---
 import '@pagefind/default-ui/css/ui.css';
 import Icon from '../user-components/Icon.astro';
+import project from 'virtual:starlight/project-context';
 import type { Props } from '../props';
 
 const { labels } = Astro.props;
@@ -15,7 +16,10 @@ const pagefindTranslations = {
 };
 ---
 
-<site-search data-translations={JSON.stringify(pagefindTranslations)}>
+<site-search
+	data-translations={JSON.stringify(pagefindTranslations)}
+	data-strip-trailing-slash={project.trailingSlash === 'never'}
+>
 	<button data-open-modal disabled>
 		{
 			/* The span is `aria-hidden` because it is not shown on small screens. Instead, the icon label is used for accessibility purposes. */
@@ -112,10 +116,15 @@ const pagefindTranslations = {
 				translations = JSON.parse(this.dataset.translations || '{}');
 			} catch {}
 
+			const shouldStrip = this.dataset.stripTrailingSlash !== undefined;
+			const stripTrailingSlash = (path: string) => path.replace(/(.)\/(#.*)?$/, '$1$2');
+			const formatURL = shouldStrip ? stripTrailingSlash : (path: string) => path;
+
 			window.addEventListener('DOMContentLoaded', () => {
 				if (import.meta.env.DEV) return;
 				const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
 				onIdle(async () => {
+					// @ts-expect-error — Missing types for @pagefind/default-ui package.
 					const { PagefindUI } = await import('@pagefind/default-ui');
 					new PagefindUI({
 						element: '#starlight__search',
@@ -124,6 +133,13 @@ const pagefindTranslations = {
 						showImages: false,
 						translations,
 						showSubResults: true,
+						processResult: (result: { url: string; sub_results: Array<{ url: string }> }) => {
+							result.url = formatURL(result.url);
+							result.sub_results = result.sub_results.map((sub_result) => {
+								sub_result.url = formatURL(sub_result.url);
+								return sub_result;
+							});
+						},
 					});
 				});
 			});

package/components.ts

@@ -4,3 +4,4 @@ export { default as Icon } from './user-components/Icon.astro';
 export { default as Tabs } from './user-components/Tabs.astro';
 export { default as TabItem } from './user-components/TabItem.astro';
 export { default as LinkCard } from './user-components/LinkCard.astro';
+export { Code } from 'astro-expressive-code/components';

package/index.ts

@@ -39,10 +39,12 @@ export default function StarlightIntegration({
 
 				const useTranslations = createTranslationSystemFromFs(starlightConfig, config);
 
-				injectRoute({
-					pattern: '404',
-					entrypoint: '@astrojs/starlight/404.astro',
-				});
+				if (!userConfig.disable404Route) {
+					injectRoute({
+						pattern: '404',
+						entrypoint: '@astrojs/starlight/404.astro',
+					});
+				}
 				injectRoute({
 					pattern: '[...slug]',
 					entrypoint: '@astrojs/starlight/index.astro',
@@ -51,9 +53,7 @@ export default function StarlightIntegration({
 				// config or by a plugin.
 				const allIntegrations = [...config.integrations, ...integrations];
 				if (!allIntegrations.find(({ name }) => name === 'astro-expressive-code')) {
-					integrations.push(
-						...starlightExpressiveCode({ starlightConfig, astroConfig: config, useTranslations })
-					);
+					integrations.push(...starlightExpressiveCode({ starlightConfig, useTranslations }));
 				}
 				if (!allIntegrations.find(({ name }) => name === '@astrojs/sitemap')) {
 					integrations.push(starlightSitemap(starlightConfig));

package/integrations/expressive-code/exports.ts

@@ -34,3 +34,37 @@
  */
 
 export * from 'astro-expressive-code';
+
+import type { StarlightExpressiveCodeOptions } from './index';
+
+export type { StarlightExpressiveCodeOptions };
+
+/**
+ * A utility function that helps you define an Expressive Code configuration object. It is meant
+ * to be used inside the optional config file `ec.config.mjs` located in the root directory
+ * of your Starlight project, and its return value to be exported as the default export.
+ *
+ * Expressive Code will automatically detect this file and use the exported configuration object
+ * to override its own default settings.
+ *
+ * Using this function is recommended, but not required. It just passes through the given object,
+ * but it also provides type information for your editor's auto-completion and type checking.
+ *
+ * @example
+ * ```js
+ * // ec.config.mjs
+ * import { defineEcConfig } from '@astrojs/starlight/expressive-code'
+ *
+ * export default defineEcConfig({
+ *   themes: ['starlight-dark', 'github-light'],
+ *   styleOverrides: {
+ *     borderRadius: '0.5rem',
+ *   },
+ * })
+ * ```
+ */
+export function defineEcConfig(config: StarlightExpressiveCodeOptions) {
+	return config;
+}
+
+export { getStarlightEcConfigPreprocessor } from './index';

package/integrations/expressive-code/index.ts

@@ -2,8 +2,9 @@ import {
 	astroExpressiveCode,
 	type AstroExpressiveCodeOptions,
 	addClassName,
+	type CustomConfigPreprocessors,
 } from 'astro-expressive-code';
-import type { AstroConfig, AstroIntegration } from 'astro';
+import type { AstroIntegration } from 'astro';
 import type { StarlightConfig } from '../../types';
 import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { pathToLocale } from '../shared/pathToLocale';
@@ -60,56 +61,59 @@ export type StarlightExpressiveCodeOptions = Omit<AstroExpressiveCodeOptions, 't
 	useStarlightUiThemeColors?: boolean | undefined;
 };
 
-export const starlightExpressiveCode = ({
-	astroConfig,
+type StarlightEcIntegrationOptions = {
+	starlightConfig: StarlightConfig;
+	useTranslations?: ReturnType<typeof createTranslationSystemFromFs> | undefined;
+};
+
+/**
+ * Create an Expressive Code configuration preprocessor based on Starlight config.
+ * Used internally to set up Expressive Code and by the `<Code>` component.
+ */
+export function getStarlightEcConfigPreprocessor({
 	starlightConfig,
 	useTranslations,
-}: {
-	astroConfig: Pick<AstroConfig, 'root' | 'srcDir'>;
-	starlightConfig: StarlightConfig;
-	useTranslations: ReturnType<typeof createTranslationSystemFromFs>;
-}): AstroIntegration[] => {
-	const { locales, expressiveCode } = starlightConfig;
-	if (expressiveCode === false) return [];
-	const config: StarlightExpressiveCodeOptions =
-		typeof expressiveCode === 'object' ? expressiveCode : {};
+}: StarlightEcIntegrationOptions): CustomConfigPreprocessors['preprocessAstroIntegrationConfig'] {
+	return (input): AstroExpressiveCodeOptions => {
+		const astroConfig = input.astroConfig;
+		const ecConfig = input.ecConfig as StarlightExpressiveCodeOptions;
+		const { locales } = starlightConfig;
 
-	const {
-		themes: themesInput,
-		customizeTheme,
-		styleOverrides: { textMarkers: textMarkersStyleOverrides, ...otherStyleOverrides } = {},
-		useStarlightDarkModeSwitch,
-		useStarlightUiThemeColors = config.themes === undefined,
-		plugins = [],
-		...rest
-	} = config;
+		const {
+			themes: themesInput,
+			customizeTheme,
+			styleOverrides: { textMarkers: textMarkersStyleOverrides, ...otherStyleOverrides } = {},
+			useStarlightDarkModeSwitch,
+			useStarlightUiThemeColors = ecConfig.themes === undefined,
+			plugins = [],
+			...rest
+		} = ecConfig;
 
-	// Handle the `themes` option
-	const themes = preprocessThemes(themesInput);
-	if (useStarlightUiThemeColors === true && themes.length < 2) {
-		console.warn(
-			`*** Warning: Using the config option "useStarlightUiThemeColors: true" ` +
-				`with a single theme is not recommended. For better color contrast, ` +
-				`please provide at least one dark and one light theme.\n`
-		);
-	}
+		// Handle the `themes` option
+		const themes = preprocessThemes(themesInput);
+		if (useStarlightUiThemeColors === true && themes.length < 2) {
+			console.warn(
+				`*** Warning: Using the config option "useStarlightUiThemeColors: true" ` +
+					`with a single theme is not recommended. For better color contrast, ` +
+					`please provide at least one dark and one light theme.\n`
+			);
+		}
 
-	// Add the `not-content` class to all rendered blocks to prevent them from being affected
-	// by Starlight's default content styles
-	plugins.push({
-		name: 'Starlight Plugin',
-		hooks: {
-			postprocessRenderedBlock: ({ renderData }) => {
-				addClassName(renderData.blockAst, 'not-content');
+		// Add the `not-content` class to all rendered blocks to prevent them from being affected
+		// by Starlight's default content styles
+		plugins.push({
+			name: 'Starlight Plugin',
+			hooks: {
+				postprocessRenderedBlock: ({ renderData }) => {
+					addClassName(renderData.blockAst, 'not-content');
+				},
 			},
-		},
-	});
+		});
 
-	// Add Expressive Code UI translations (if any) for all defined locales
-	addTranslations(locales, useTranslations);
+		// Add Expressive Code UI translations (if any) for all defined locales
+		if (useTranslations) addTranslations(locales, useTranslations);
 
-	return [
-		astroExpressiveCode({
+		return {
 			themes,
 			customizeTheme: (theme) => {
 				if (useStarlightUiThemeColors) {
@@ -151,6 +155,36 @@ export const starlightExpressiveCode = ({
 			getBlockLocale: ({ file }) => pathToLocale(file.path, { starlightConfig, astroConfig }),
 			plugins,
 			...rest,
+		};
+	};
+}
+
+export const starlightExpressiveCode = ({
+	starlightConfig,
+	useTranslations,
+}: StarlightEcIntegrationOptions): AstroIntegration[] => {
+	if (starlightConfig.expressiveCode === false) return [];
+
+	const configArgs =
+		typeof starlightConfig.expressiveCode === 'object'
+			? (starlightConfig.expressiveCode as AstroExpressiveCodeOptions)
+			: {};
+	return [
+		astroExpressiveCode({
+			...configArgs,
+			customConfigPreprocessors: {
+				preprocessAstroIntegrationConfig: getStarlightEcConfigPreprocessor({
+					starlightConfig,
+					useTranslations,
+				}),
+				preprocessComponentConfig: `
+					import starlightConfig from 'virtual:starlight/user-config'
+					import { useTranslations } from '@astrojs/starlight/internal'
+					import { getStarlightEcConfigPreprocessor } from '@astrojs/starlight/expressive-code'
+
+					export default getStarlightEcConfigPreprocessor({ starlightConfig, useTranslations })
+				`,
+			},
 		}),
 	];
 };

package/integrations/expressive-code/theming.ts

@@ -1,5 +1,6 @@
-import fs from 'node:fs';
 import { ExpressiveCodeTheme, type ThemeObjectOrShikiThemeName } from 'astro-expressive-code';
+import nightOwlDark from './themes/night-owl-dark.jsonc?raw';
+import nightOwlLight from './themes/night-owl-light.jsonc?raw';
 
 export type BundledThemeName = 'starlight-dark' | 'starlight-light';
 
@@ -20,13 +21,8 @@ export function preprocessThemes(
 	return themes.map((theme) => {
 		// If the current entry is the name of a bundled theme, load it
 		if (theme === 'starlight-dark' || theme === 'starlight-light') {
-			const bundledThemeFile =
-				theme === 'starlight-dark' ? 'night-owl-dark.jsonc' : 'night-owl-light.jsonc';
-			return customizeBundledTheme(
-				ExpressiveCodeTheme.fromJSONString(
-					fs.readFileSync(new URL(`./themes/${bundledThemeFile}`, import.meta.url), 'utf-8')
-				)
-			);
+			const bundledTheme = theme === 'starlight-dark' ? nightOwlDark : nightOwlLight;
+			return customizeBundledTheme(ExpressiveCodeTheme.fromJSONString(bundledTheme));
 		}
 		// Otherwise, just pass it through
 		return theme;

package/integrations/shared/pathToLocale.ts

@@ -22,11 +22,13 @@ export function pathToLocale(
 ): string | undefined {
 	const srcDir = new URL(astroConfig.srcDir, astroConfig.root);
 	const docsDir = new URL('content/docs/', srcDir);
-	const slug = path
-		// Format path to unix style path.
-		?.replace(/\\/g, '/')
-		// Strip docs path leaving only content collection file ID.
-		// Example: /Users/houston/repo/src/content/docs/en/guide.md => en/guide.md
-		.replace(docsDir.pathname, '');
+	// Format path to unix style path.
+	path = path?.replace(/\\/g, '/');
+	// Ensure that the page path starts with a slash if the docs directory also does,
+	// which makes stripping the docs path in the next step work on Windows, too.
+	if (path && !path.startsWith('/') && docsDir.pathname.startsWith('/')) path = '/' + path;
+	// Strip docs path leaving only content collection file ID.
+	// Example: /Users/houston/repo/src/content/docs/en/guide.md => en/guide.md
+	const slug = path?.replace(docsDir.pathname, '');
 	return slugToLocale(slug, starlightConfig.locales);
 }

package/internal.ts

@@ -0,0 +1 @@
+export { useTranslations } from './utils/translations';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -150,6 +150,7 @@
       "types": "./components/Search.astro.tsx",
       "import": "./components/Search.astro"
     },
+    "./internal": "./internal.ts",
     "./props": "./props.ts",
     "./schema": "./schema.ts",
     "./types": "./types.ts",
@@ -174,7 +175,7 @@
     "@pagefind/default-ui": "^1.0.3",
     "@types/hast": "^3.0.3",
     "@types/mdast": "^4.0.3",
-    "astro-expressive-code": "^0.31.0",
+    "astro-expressive-code": "^0.32.2",
     "bcp-47": "^2.1.0",
     "hast-util-select": "^6.0.2",
     "hastscript": "^8.0.0",

package/style/props.css

@@ -87,8 +87,8 @@
 		'Segoe UI Symbol', 'Noto Color Emoji';
 	--sl-font-system-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
 		'Courier New', monospace;
-	--__sl-font: var(--sl-font, ''), var(--sl-font-system);
-	--__sl-font-mono: var(--sl-font-mono, ''), var(--sl-font-system-mono);
+	--__sl-font: var(--sl-font, var(--sl-font-system)), var(--sl-font-system);
+	--__sl-font-mono: var(--sl-font-mono, var(--sl-font-system-mono)), var(--sl-font-system-mono);
 
 	/** Key layout values */
 	--sl-nav-height: 3.5rem;

package/utils/user-config.ts

@@ -205,6 +205,9 @@ const UserConfigSchema = z.object({
 		.string()
 		.default('|')
 		.describe('Will be used as title delimiter in the generated `<title>` tag.'),
+
+	/** Disable Starlight's default 404 page. */
+	disable404Route: z.boolean().default(false).describe("Disable Starlight's default 404 page."),
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(