@astrojs/starlight 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @astrojs/starlight
 
+## 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.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,5 @@
  */
 
 export * from 'astro-expressive-code';
+
+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.0",
   "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/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(