@astrojs/starlight 0.41.11 → 0.42.0

package/dist/utils/user-config.js

@@ -0,0 +1,136 @@
+import { BuiltInDefaultLocale } from "./i18n.js";
+import { ComponentConfigSchema } from "../schemas/components.js";
+import { ExpressiveCodeSchema } from "../schemas/expressiveCode.js";
+import { FaviconSchema } from "../schemas/favicon.js";
+import { HeadConfigSchema } from "../schemas/head.js";
+import { LogoConfigSchema } from "../schemas/logo.js";
+import { PagefindConfigDefaults, PagefindConfigSchema } from "../schemas/pagefind.js";
+import { SidebarItemSchema } from "../schemas/sidebar.js";
+import { TitleConfigSchema, TitleTransformConfigSchema } from "../schemas/site-title.js";
+import { SocialLinksSchema } from "../schemas/social.js";
+import { UserConfigTableOfContentsSchema } from "../schemas/tableOfContents.js";
+import { LocaleConfigSchema } from "../schemas/locale.js";
+import { z } from "astro/zod";
+import { parse, stringify } from "bcp-47";
+//#region src/utils/user-config.ts
+const UserConfigSchema = z.object({
+	title: TitleConfigSchema(),
+	description: z.string().optional(),
+	logo: LogoConfigSchema(),
+	social: SocialLinksSchema(),
+	tableOfContents: UserConfigTableOfContentsSchema(),
+	editLink: z.object({ baseUrl: z.url().optional() }).optional().default({}),
+	locales: z.object({ root: LocaleConfigSchema().required({ lang: true }).optional() }).catchall(LocaleConfigSchema()).transform((locales, ctx) => {
+		for (const key in locales) {
+			const locale = locales[key];
+			let lang = locale.lang || key;
+			const schema = parse(lang, { forgiving: true });
+			schema.region = schema.region?.toUpperCase();
+			const normalizedLang = stringify(schema);
+			if (!normalizedLang) {
+				ctx.issues.push({
+					code: "custom",
+					message: `Could not validate language tag "${lang}" at locales.${key}.lang.`,
+					input: lang
+				});
+				return z.NEVER;
+			}
+			if (normalizedLang !== lang) {
+				console.warn(`Warning: using "${normalizedLang}" language tag for locales.${key}.lang instead of "${lang}".`);
+				lang = normalizedLang;
+			}
+			locale.lang = lang;
+		}
+		return locales;
+	}).optional(),
+	defaultLocale: z.string().optional(),
+	sidebar: SidebarItemSchema.array().optional(),
+	head: HeadConfigSchema({ source: "config" }),
+	customCss: z.string().array().optional().default([]).superRefine((paths, ctx) => {
+		const invalidPathRegex = /^\.?\/public\/.+$/;
+		const invalidPaths = paths.filter((path) => invalidPathRegex.test(path));
+		if (invalidPaths.length > 0) ctx.issues.push({
+			code: "custom",
+			message: `These paths in your Starlight \`customCss\` config are invalid: ${invalidPaths.map((path) => `\`"${path}"\``).join(", ")}\n\nCSS files specified in \`customCss\` should be in the \`src/\` directory, not the \`public/\` directory.\n\nYou should move these CSS files into the \`src/\` directory and update the path in \`customCss\` to match.`,
+			input: paths
+		});
+	}),
+	lastUpdated: z.boolean().default(false),
+	pagination: z.boolean().default(true),
+	favicon: FaviconSchema(),
+	expressiveCode: ExpressiveCodeSchema(),
+	pagefind: z.boolean().transform((val) => val && PagefindConfigDefaults()).or(PagefindConfigSchema()).optional(),
+	components: ComponentConfigSchema(),
+	titleDelimiter: z.string().default("|"),
+	disable404Route: z.boolean().default(false),
+	prerender: z.boolean().default(true),
+	credits: z.boolean().default(false),
+	routeMiddleware: z.string().transform((string) => [string]).or(z.string().array()).default([]).superRefine((middlewares, ctx) => {
+		const invalidPathRegex = /^\.?\/src\/middleware(?:\/index)?\.[jt]s$/;
+		const invalidPaths = middlewares.filter((middleware) => invalidPathRegex.test(middleware));
+		for (const invalidPath of invalidPaths) ctx.issues.push({
+			code: "custom",
+			message: `The \`"${invalidPath}"\` path in your Starlight \`routeMiddleware\` config conflicts with Astro’s middleware locations.\n\nYou should rename \`${invalidPath}\` to something else like \`./src/starlightRouteData.ts\` and update the \`routeMiddleware\` file path to match.\n\n- More about Starlight route middleware: https://starlight.astro.build/guides/route-data/#how-to-customize-route-data
+- More about Astro middleware: https://docs.astro.build/en/guides/middleware/`,
+			input: middlewares
+		});
+	}),
+	markdown: z.object({
+		headingLinks: z.boolean().default(true),
+		processedDirs: z.string().array().default([])
+	}).prefault({})
+});
+const StarlightConfigSchema = z.strictObject({ ...UserConfigSchema.shape }).transform((config) => ({
+	...config,
+	pagefind: typeof config.pagefind === "undefined" ? config.prerender && PagefindConfigDefaults() : config.pagefind
+})).refine((config) => !(!config.prerender && config.pagefind), { error: "Pagefind search is not supported with prerendering disabled." }).transform(({ title, locales, defaultLocale, ...config }, ctx) => {
+	const configuredLocales = Object.keys(locales ?? {});
+	if (locales !== void 0 && (configuredLocales.length > 1 || configuredLocales.length === 1 && locales.root === void 0)) {
+		const defaultLocaleConfig = locales[defaultLocale || "root"];
+		if (!defaultLocaleConfig) {
+			const availableLocales = configuredLocales.map((l) => `"${l}"`).join(", ");
+			ctx.issues.push({
+				code: "custom",
+				message: "Could not determine the default locale. Please make sure `defaultLocale` in your Starlight config is one of " + availableLocales,
+				input: locales
+			});
+			return z.NEVER;
+		}
+		const parsedTitle = TitleTransformConfigSchema(defaultLocaleConfig.lang).parse(title);
+		return {
+			...config,
+			title: parsedTitle,
+			/** Flag indicating if this site has multiple locales set up. */
+			isMultilingual: configuredLocales.length > 1,
+			/** Flag indicating if the Starlight built-in default locale is used. */
+			isUsingBuiltInDefaultLocale: false,
+			/** Full locale object for this site’s default language. */
+			defaultLocale: {
+				...defaultLocaleConfig,
+				locale: defaultLocale
+			},
+			locales
+		};
+	}
+	/** Full locale object for this site’s default language. */
+	const defaultLocaleConfig = {
+		label: BuiltInDefaultLocale.label,
+		lang: BuiltInDefaultLocale.lang,
+		dir: BuiltInDefaultLocale.dir,
+		locale: void 0,
+		...locales?.root
+	};
+	const parsedTitle = TitleTransformConfigSchema(defaultLocaleConfig.lang).parse(title);
+	return {
+		...config,
+		title: parsedTitle,
+		/** Flag indicating if this site has multiple locales set up. */
+		isMultilingual: false,
+		/** Flag indicating if the Starlight built-in default locale is used. */
+		isUsingBuiltInDefaultLocale: locales?.root === void 0,
+		defaultLocale: defaultLocaleConfig,
+		locales: void 0
+	};
+});
+//#endregion
+export { StarlightConfigSchema };

package/dist/utils/validateLogoImports.d.ts

@@ -0,0 +1,5 @@
+//#region src/utils/validateLogoImports.d.ts
+/** Check user-imported logo images have resolved correctly. */
+declare function validateLogoImports(): void;
+//#endregion
+export { validateLogoImports };

package/dist/utils/validateLogoImports.js

@@ -0,0 +1,16 @@
+import config from "virtual:starlight/user-config";
+import { logos } from "virtual:starlight/user-images";
+//#region src/utils/validateLogoImports.ts
+/** Check user-imported logo images have resolved correctly. */
+function validateLogoImports() {
+	if (config.logo) {
+		let err;
+		if ("src" in config.logo) {
+			if (!logos.dark || !logos.light) err = `Could not resolve logo import for "${config.logo.src}" (logo.src)`;
+		} else if (!logos.dark) err = `Could not resolve logo import for "${config.logo.dark}" (logo.dark)`;
+		else if (!logos.light) err = `Could not resolve logo import for "${config.logo.light}" (logo.light)`;
+		if (err) throw new Error(err);
+	}
+}
+//#endregion
+export { validateLogoImports };

package/dist/utils/zodDeepMerge.d.ts

@@ -0,0 +1,16 @@
+import { z } from "astro/zod";
+//#region src/utils/zodDeepMerge.d.ts
+/** Type-level equivalent of {@link mergeWithDefaultSchema}. */
+type DeepMergedSchema<Default extends z.core.$ZodType, User extends z.core.$ZodType> = User extends z.ZodOptional<infer WrappedSchema extends z.core.$ZodType> ? z.ZodOptional<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>> : User extends z.ZodNullable<infer WrappedSchema extends z.core.$ZodType> ? z.ZodNullable<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>> : User extends z.ZodDefault<infer WrappedSchema extends z.core.$ZodType> ? z.ZodDefault<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>> : User extends z.ZodPrefault<infer WrappedSchema extends z.core.$ZodType> ? z.ZodPrefault<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>> : User extends z.ZodUnion<infer Users extends readonly z.core.$ZodType[]> ? z.ZodUnion<DeepMergedUnionMembers<UnwrappedSchema<Default>, Users>> : UnwrappedSchema<Default> extends z.ZodObject<infer DefaultShape> ? User extends z.ZodObject<infer UserShape, infer UserConfig> ? z.ZodObject<DeepMergedShape<DefaultShape, UserShape>, UserConfig> : User : UnwrappedSchema<Default> extends z.ZodArray<infer DefaultItemSchema extends z.core.$ZodType> ? User extends z.ZodArray<infer UserItemSchema extends z.core.$ZodType> ? z.ZodArray<DeepMergedSchema<DefaultItemSchema, UserItemSchema>> : User : User;
+/** Type-level equivalent of {@link unwrapSchema}. */
+type UnwrappedSchema<T extends z.core.$ZodType> = T extends z.ZodOptional<infer Wrapped extends z.core.$ZodType> ? UnwrappedSchema<Wrapped> : T extends z.ZodNullable<infer Wrapped extends z.core.$ZodType> ? UnwrappedSchema<Wrapped> : T extends z.ZodDefault<infer Wrapped extends z.core.$ZodType> ? UnwrappedSchema<Wrapped> : T extends z.ZodPrefault<infer Wrapped extends z.core.$ZodType> ? UnwrappedSchema<Wrapped> : T;
+/**
+ * Merged Zod object shapes, preserving default properties, adding user-only properties, and
+ * recursively merging shared properties.
+ */
+type DeepMergedShape<Default extends z.ZodRawShape, User extends z.ZodRawShape> = { [Key in keyof Default | keyof User]: Key extends keyof User ? Key extends keyof Default ? DeepMergedSchema<Default[Key], User[Key]> : User[Key] : Key extends keyof Default ? Default[Key] : never; };
+/** Merged union schemas where each union member is deep-merged with the default schema. */
+type DeepMergedUnionMembers<Default extends z.core.$ZodType, Users extends readonly z.core.$ZodType[]> = { [Key in keyof Users]: Users[Key] extends z.core.$ZodType ? DeepMergedSchema<Default, Users[Key]> : Users[Key]; };
+declare function deepMergeSchemas(defaultSchema: z.ZodType, userSchema: z.ZodType): z.ZodType;
+//#endregion
+export { DeepMergedSchema, deepMergeSchemas };

package/dist/utils/zodDeepMerge.js

@@ -0,0 +1,53 @@
+//#region src/utils/zodDeepMerge.ts
+function deepMergeSchemas(defaultSchema, userSchema) {
+	const unwrappedDefaultSchema = unwrapSchema(defaultSchema);
+	if (isWrappedSchema(userSchema)) return userSchema.clone({
+		...userSchema._zod.def,
+		innerType: deepMergeSchemas(unwrappedDefaultSchema, userSchema._zod.def.innerType)
+	});
+	if (isZodUnion(userSchema)) return userSchema.clone({
+		...userSchema._zod.def,
+		options: userSchema.options.map((schema) => deepMergeSchemas(unwrappedDefaultSchema, schema))
+	});
+	if (isZodObject(unwrappedDefaultSchema) && isZodObject(userSchema)) {
+		const shape = { ...unwrappedDefaultSchema.shape };
+		for (const key of Object.keys(userSchema.shape)) {
+			const userFieldSchema = userSchema.shape[key];
+			const defaultFieldSchema = shape[key];
+			shape[key] = defaultFieldSchema ? deepMergeSchemas(defaultFieldSchema, userFieldSchema) : userFieldSchema;
+		}
+		return userSchema.safeExtend(shape);
+	}
+	if (isZodArray(unwrappedDefaultSchema) && isZodArray(userSchema)) return userSchema.clone({
+		...userSchema._zod.def,
+		element: deepMergeSchemas(unwrappedDefaultSchema.element, userSchema.element)
+	});
+	return userSchema;
+}
+/**
+* Unwrap any Zod schema that wraps other schemas, such as `z.optional()`, `z.nullable()`,
+* `z.default()`, etc. until we reach the innermost schema.
+*/
+function unwrapSchema(schema) {
+	let current = schema;
+	while (isWrappedSchema(current)) current = current._zod.def.innerType;
+	return current;
+}
+/**
+* Check if a schema wraps another schema which can happen when using modifiers like
+* `z.optional()`, `z.nullable()`, `z.default()`, etc.
+*/
+function isWrappedSchema(schema) {
+	return schema._zod.def.type === "optional" || schema._zod.def.type === "nullable" || schema._zod.def.type === "default" || schema._zod.def.type === "prefault";
+}
+function isZodObject(schema) {
+	return schema._zod.def.type === "object";
+}
+function isZodArray(schema) {
+	return schema._zod.def.type === "array";
+}
+function isZodUnion(schema) {
+	return schema._zod.def.type === "union";
+}
+//#endregion
+export { deepMergeSchemas };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.41.11",
+  "version": "0.42.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -13,37 +13,61 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/withastro/starlight",
+    "url": "git+https://github.com/withastro/starlight.git",
     "directory": "packages/starlight"
   },
   "bugs": "https://github.com/withastro/starlight/issues",
   "homepage": "https://starlight.astro.build",
   "type": "module",
   "exports": {
-    ".": "./index.ts",
-    "./locals": "./locals.ts",
-    "./components": "./components.ts",
-    "./components/*": "./components/*",
-    "./internal": "./internal.ts",
-    "./props": "./props.ts",
-    "./schema": "./schema.ts",
-    "./loaders": "./loaders.ts",
-    "./route-data": "./route-data.ts",
-    "./types": "./types.ts",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./locals": {
+      "types": "./dist/locals.d.ts",
+      "import": "./dist/locals.js"
+    },
+    "./components": "./dist/components.ts",
+    "./components/*": "./dist/components/*",
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    },
+    "./props": {
+      "types": "./dist/props.d.ts",
+      "import": "./dist/props.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
+    "./loaders": {
+      "types": "./dist/loaders.d.ts",
+      "import": "./dist/loaders.js"
+    },
+    "./route-data": {
+      "types": "./dist/route-data.d.ts",
+      "import": "./dist/route-data.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
     "./expressive-code": {
-      "types": "./expressive-code.d.ts",
-      "default": "./expressive-code.mjs"
+      "types": "./dist/expressive-code.d.ts",
+      "import": "./dist/expressive-code.js"
     },
     "./expressive-code/hast": {
-      "types": "./integrations/expressive-code/hast.d.ts",
-      "default": "./integrations/expressive-code/hast.mjs"
+      "types": "./dist/integrations/expressive-code/hast.d.ts",
+      "import": "./dist/integrations/expressive-code/hast.js"
     },
-    "./routes/*": "./routes/*",
-    "./style/markdown.css": "./style/markdown.css"
+    "./routes/*": "./dist/routes/*",
+    "./style/markdown.css": "./dist/style/markdown.css"
   },
   "peerDependencies": {
-    "@astrojs/markdown-remark": "^7.2.0",
-    "astro": "^7.0.2"
+    "@astrojs/markdown-remark": "^7.3.0",
+    "astro": "^7.2.10"
   },
   "peerDependenciesMeta": {
     "@astrojs/markdown-remark": {
@@ -51,52 +75,54 @@
     }
   },
   "devDependencies": {
-    "@astrojs/markdown-remark": "^7.2.2",
-    "@playwright/test": "^1.61.1",
+    "@astrojs/markdown-remark": "^7.3.0",
     "@codspeed/vitest-plugin": "^5.7.1",
+    "@playwright/test": "^1.61.1",
     "@types/node": "^22.19.17",
     "@vitest/coverage-v8": "^4.1.5",
-    "astro": "^7.1.6",
+    "astro": "^7.2.10",
     "linkedom": "^0.18.12",
     "vitest": "^4.1.5"
   },
   "dependencies": {
-    "@astrojs/markdown-satteri": "^0.3.5",
-    "@astrojs/mdx": "^7.0.5",
+    "@astrojs/markdown-satteri": "^0.4.0",
+    "@astrojs/mdx": "^8.0.0",
     "@astrojs/sitemap": "^3.7.3",
     "@pagefind/default-ui": "^1.3.0",
-    "@types/hast": "^3.0.4",
+    "@types/hast": "^3.0.5",
     "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
     "astro-expressive-code": "^0.44.0",
     "bcp-47": "^2.1.0",
-    "hast-util-from-html": "^2.0.3",
+    "hast-util-format": "^1.1.0",
     "hast-util-select": "^6.0.4",
+    "hast-util-to-html": "^9.0.5",
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
     "i18next": "^26.0.7",
     "js-yaml": "^4.1.1",
     "klona": "^2.0.6",
-    "magic-string": "^0.30.21",
+    "magic-string": "^1.2.3",
     "mdast-util-directive": "^3.1.0",
     "mdast-util-to-markdown": "^2.1.2",
     "mdast-util-to-string": "^4.0.0",
     "pagefind": "^1.5.2",
-    "rehype": "^13.0.2",
-    "rehype-format": "^5.0.1",
     "remark-directive": "^4.0.0",
-    "satteri": "^0.9.1",
+    "satteri": "^0.10.3",
     "ultrahtml": "^1.6.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "vfile": "^6.0.3"
   },
-  "publishConfig": {
-    "provenance": true
-  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
+    "build": "tsdown",
     "test": "VITE_CONFIG_NATIVE_IGNORE_WARNING=true vitest",
     "test:coverage": "VITE_CONFIG_NATIVE_IGNORE_WARNING=true vitest run --coverage",
+    "test:dist": "pnpm build && pnpm test:dist:ci",
+    "test:dist:ci": "VITE_CONFIG_NATIVE_IGNORE_WARNING=true STARLIGHT_TEST_DIST=true vitest run",
     "bench": "pnpm bench:functional",
     "bench:functional": "VITE_CONFIG_NATIVE_IGNORE_WARNING=true vitest bench --run --config vitest.functional.bench.config.ts __bench_fn__/*.bench.ts",
     "test:e2e": "playwright install --with-deps chromium && playwright test",