@astrojs/starlight 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @astrojs/starlight
 
+## 0.20.0
+
+### Minor Changes
+
+- [#1541](https://github.com/withastro/starlight/pull/1541) [`1043052f`](https://github.com/withastro/starlight/commit/1043052f3890a577a73276472f3773924909406b) Thanks [@hippotastic](https://github.com/hippotastic)! - Updates `astro-expressive-code` dependency to the latest minor release (0.33).
+
+  This unlocks support for [word wrap](https://expressive-code.com/key-features/word-wrap/) and [line numbers](https://expressive-code.com/plugins/line-numbers/), as well as updating the syntax highlighter to the latest Shiki release, which includes new and updated language grammars.
+
+  See the [Expressive Code release notes](https://expressive-code.com/releases/) for more information including details of potentially breaking changes.
+
+### Patch Changes
+
+- [#1542](https://github.com/withastro/starlight/pull/1542) [`b3b7a606`](https://github.com/withastro/starlight/commit/b3b7a6069952d5f27a49b2fd097aa4db065e1718) Thanks [@delucis](https://github.com/delucis)! - Improves error messages shown by Starlight for configuration errors.
+
+- [#1544](https://github.com/withastro/starlight/pull/1544) [`65dc6586`](https://github.com/withastro/starlight/commit/65dc6586ef7c1754875db1d48c49e709051a0b13) Thanks [@torn4dom4n](https://github.com/torn4dom4n)! - Update Vietnamese UI translations
+
+## 0.19.1
+
+### Patch Changes
+
+- [#1527](https://github.com/withastro/starlight/pull/1527) [`163bc84`](https://github.com/withastro/starlight/commit/163bc848e173eecca92d1cb034045fdb42aa4ff1) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Exports the `StarlightPageProps` TypeScript type representing the props expected by the `<StarlightPage />` component.
+
+- [#1504](https://github.com/withastro/starlight/pull/1504) [`fc83a05`](https://github.com/withastro/starlight/commit/fc83a05235b74be2bfe6ba8e7f95a8a5a618ead3) Thanks [@mingjunlu](https://github.com/mingjunlu)! - Adds Traditional Chinese UI translations
+
+- [#1534](https://github.com/withastro/starlight/pull/1534) [`aada680`](https://github.com/withastro/starlight/commit/aada6805abc0068f07393585b86978ef5200439c) Thanks [@delucis](https://github.com/delucis)! - Improves DX of the `sidebar` prop used by the new `<StarlightPage>` component.
+
 ## 0.19.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -172,9 +172,9 @@
   "devDependencies": {
     "@astrojs/markdown-remark": "^4.2.1",
     "@types/node": "^18.16.19",
-    "@vitest/coverage-v8": "^1.2.2",
+    "@vitest/coverage-v8": "^1.3.1",
     "astro": "^4.3.5",
-    "vitest": "^1.2.2"
+    "vitest": "^1.3.1"
   },
   "dependencies": {
     "@astrojs/mdx": "^2.1.1",
@@ -182,7 +182,7 @@
     "@pagefind/default-ui": "^1.0.3",
     "@types/hast": "^3.0.3",
     "@types/mdast": "^4.0.3",
-    "astro-expressive-code": "^0.32.4",
+    "astro-expressive-code": "^0.33.2",
     "bcp-47": "^2.1.0",
     "hast-util-select": "^6.0.2",
     "hastscript": "^8.0.0",

package/props.ts

@@ -1 +1,2 @@
 export type { StarlightRouteData as Props } from './utils/route-data';
+export type { StarlightPageProps } from './utils/starlight-page';

package/translations/index.ts

@@ -24,6 +24,7 @@ import ru from './ru.json';
 import vi from './vi.json';
 import uk from './uk.json';
 import hi from './hi.json';
+import zhTW from './zh-TW.json';
 
 const { parse } = builtinI18nSchema();
 
@@ -54,5 +55,6 @@ export default Object.fromEntries(
 		vi,
 		uk,
 		hi,
+		'zh-TW': zhTW,
 	}).map(([key, dict]) => [key, parse(dict)])
 );

package/translations/vi.json

@@ -19,8 +19,8 @@
   "page.previousLink": "Tiếp",
   "page.nextLink": "Trước",
   "404.text": "Không tìm thấy trang. Kiểm tra URL hoặc thử sử dụng thanh tìm kiếm.",
-  "aside.note": "Note",
-  "aside.tip": "Tip",
-  "aside.caution": "Caution",
-  "aside.danger": "Danger"
+  "aside.note": "Ghi chú",
+  "aside.tip": "Mẹo",
+  "aside.caution": "Thận trọng",
+  "aside.danger": "Nguy hiểm"
 }

package/translations/zh-TW.json

@@ -0,0 +1,26 @@
+{
+  "skipLink.label": "跳到內容",
+  "search.label": "搜尋",
+  "search.shortcutLabel": "（按 / 鍵開始搜尋）",
+  "search.cancelLabel": "取消",
+  "search.devWarning": "正式版本才能使用搜尋功能。\n如要在本地測試，請先建置並預覽網站。",
+  "themeSelect.accessibleLabel": "選擇佈景主題",
+  "themeSelect.dark": "深色",
+  "themeSelect.light": "淺色",
+  "themeSelect.auto": "自動",
+  "languageSelect.accessibleLabel": "選擇語言",
+  "menuButton.accessibleLabel": "選單",
+  "sidebarNav.accessibleLabel": "主要",
+  "tableOfContents.onThisPage": "本頁內容",
+  "tableOfContents.overview": "概述",
+  "i18n.untranslatedContent": "本頁內容尚未翻譯。",
+  "page.editLink": "編輯頁面",
+  "page.lastUpdated": "最後更新於：",
+  "page.previousLink": "前一則",
+  "page.nextLink": "下一則",
+  "404.text": "找不到頁面。請檢查網址或改用搜尋功能。",
+  "aside.note": "注意",
+  "aside.tip": "提示",
+  "aside.caution": "警告",
+  "aside.danger": "危險"
+}

package/utils/error-map.ts

@@ -3,6 +3,7 @@
  * source: https://github.com/withastro/astro/blob/main/packages/astro/src/content/error-map.ts
  */
 
+import { AstroError } from 'astro/errors';
 import type { z } from 'astro:content';
 
 type TypeOrLiteralErrByPathEntry = {
@@ -11,11 +12,27 @@ type TypeOrLiteralErrByPathEntry = {
 	expected: unknown[];
 };
 
-export function throwValidationError(error: z.ZodError, message: string): never {
-	throw new Error(`${message}\n${error.issues.map((i) => i.message).join('\n')}`);
+/**
+ * Parse data with a Zod schema and throw a nicely formatted error if it is invalid.
+ *
+ * @param schema The Zod schema to use to parse the input.
+ * @param input Input data that should match the schema.
+ * @param message Error message preamble to use if the input fails to parse.
+ * @returns Validated data parsed by Zod.
+ */
+export function parseWithFriendlyErrors<T extends z.Schema>(
+	schema: T,
+	input: z.input<T>,
+	message: string
+): z.output<T> {
+	const parsedConfig = schema.safeParse(input, { errorMap });
+	if (!parsedConfig.success) {
+		throw new AstroError(message, parsedConfig.error.issues.map((i) => i.message).join('\n'));
+	}
+	return parsedConfig.data;
 }
 
-export const errorMap: z.ZodErrorMap = (baseError, ctx) => {
+const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 	const baseErrorPath = flattenErrorPath(baseError.path);
 	if (baseError.code === 'invalid_union') {
 		// Optimization: Combine type and literal errors for keys that are common across ALL union types
@@ -38,30 +55,51 @@ export const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 				}
 			}
 		}
-		let messages: string[] = [
-			prefix(
-				baseErrorPath,
-				typeOrLiteralErrByPath.size ? 'Did not match union:' : 'Did not match union.'
-			),
-		];
+		const messages: string[] = [prefix(baseErrorPath, 'Did not match union.')];
+		const details: string[] = [...typeOrLiteralErrByPath.entries()]
+			// If type or literal error isn't common to ALL union types,
+			// filter it out. Can lead to confusing noise.
+			.filter(([, error]) => error.expected.length === baseError.unionErrors.length)
+			.map(([key, error]) =>
+				key === baseErrorPath
+					? // Avoid printing the key again if it's a base error
+					  `> ${getTypeOrLiteralMsg(error)}`
+					: `> ${prefix(key, getTypeOrLiteralMsg(error))}`
+			);
+
+		if (details.length === 0) {
+			const expectedShapes: string[] = [];
+			for (const unionError of baseError.unionErrors) {
+				const expectedShape: string[] = [];
+				for (const issue of unionError.issues) {
+					// If the issue is a nested union error, show the associated error message instead of the
+					// base error message.
+					if (issue.code === 'invalid_union') {
+						return errorMap(issue, ctx);
+					}
+					const relativePath = flattenErrorPath(issue.path)
+						.replace(baseErrorPath, '')
+						.replace(leadingPeriod, '');
+					if ('expected' in issue && typeof issue.expected === 'string') {
+						expectedShape.push(
+							relativePath ? `${relativePath}: ${issue.expected}` : issue.expected
+						);
+					} else {
+						expectedShape.push(relativePath);
+					}
+				}
+				expectedShapes.push(`{ ${expectedShape.join('; ')} }`);
+			}
+			if (expectedShapes.length) {
+				details.push('> Expected type `' + expectedShapes.join(' | ') + '`');
+				details.push('> Received `' + stringify(ctx.data) + '`');
+			}
+		}
+
 		return {
-			message: messages
-				.concat(
-					[...typeOrLiteralErrByPath.entries()]
-						// If type or literal error isn't common to ALL union types,
-						// filter it out. Can lead to confusing noise.
-						.filter(([, error]) => error.expected.length === baseError.unionErrors.length)
-						.map(([key, error]) =>
-							key === baseErrorPath
-								? // Avoid printing the key again if it's a base error
-								  `> ${getTypeOrLiteralMsg(error)}`
-								: `> ${prefix(key, getTypeOrLiteralMsg(error))}`
-						)
-				)
-				.join('\n'),
+			message: messages.concat(details).join('\n'),
 		};
-	}
-	if (baseError.code === 'invalid_literal' || baseError.code === 'invalid_type') {
+	} else if (baseError.code === 'invalid_literal' || baseError.code === 'invalid_type') {
 		return {
 			message: prefix(
 				baseErrorPath,
@@ -84,25 +122,25 @@ const getTypeOrLiteralMsg = (error: TypeOrLiteralErrByPathEntry): string => {
 	const expectedDeduped = new Set(error.expected);
 	switch (error.code) {
 		case 'invalid_type':
-			return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received ${JSON.stringify(
+			return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
 				error.received
-			)}`;
+			)}\``;
 		case 'invalid_literal':
-			return `Expected \`${unionExpectedVals(expectedDeduped)}\`, received ${JSON.stringify(
+			return `Expected \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
 				error.received
-			)}`;
+			)}\``;
 	}
 };
 
 const prefix = (key: string, msg: string) => (key.length ? `**${key}**: ${msg}` : msg);
 
 const unionExpectedVals = (expectedVals: Set<unknown>) =>
-	[...expectedVals]
-		.map((expectedVal, idx) => {
-			if (idx === 0) return JSON.stringify(expectedVal);
-			const sep = ' | ';
-			return `${sep}${JSON.stringify(expectedVal)}`;
-		})
-		.join('');
+	[...expectedVals].map((expectedVal) => stringify(expectedVal)).join(' | ');
 
 const flattenErrorPath = (errorPath: (string | number)[]) => errorPath.join('.');
+
+/** `JSON.stringify()` a value with spaces around object/array entries. */
+const stringify = (val: unknown) =>
+	JSON.stringify(val, null, 1).split(newlinePlusWhitespace).join(' ');
+const newlinePlusWhitespace = /\n\s*/;
+const leadingPeriod = /^\./;

package/utils/plugins.ts

@@ -1,7 +1,7 @@
 import type { AstroIntegration } from 'astro';
 import { z } from 'astro/zod';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../utils/user-config';
-import { errorMap, throwValidationError } from '../utils/error-map';
+import { parseWithFriendlyErrors } from '../utils/error-map';
 
 /**
  * Runs Starlight plugins in the order that they are configured after validating the user-provided
@@ -15,23 +15,19 @@ export async function runPlugins(
 ) {
 	// Validate the user-provided configuration.
 	let userConfig = starlightUserConfig;
-	let starlightConfig = StarlightConfigSchema.safeParse(userConfig, { errorMap });
 
-	if (!starlightConfig.success) {
-		throwValidationError(starlightConfig.error, 'Invalid config passed to starlight integration');
-	}
+	let starlightConfig = parseWithFriendlyErrors(
+		StarlightConfigSchema,
+		userConfig,
+		'Invalid config passed to starlight integration'
+	);
 
 	// Validate the user-provided plugins configuration.
-	const pluginsConfig = starlightPluginsConfigSchema.safeParse(pluginsUserConfig, {
-		errorMap,
-	});
-
-	if (!pluginsConfig.success) {
-		throwValidationError(
-			pluginsConfig.error,
-			'Invalid plugins config passed to starlight integration'
-		);
-	}
+	const pluginsConfig = parseWithFriendlyErrors(
+		starlightPluginsConfigSchema,
+		pluginsUserConfig,
+		'Invalid plugins config passed to starlight integration'
+	);
 
 	// A list of Astro integrations added by the various plugins.
 	const integrations: AstroIntegration[] = [];
@@ -39,7 +35,7 @@ export async function runPlugins(
 	for (const {
 		name,
 		hooks: { setup },
-	} of pluginsConfig.data) {
+	} of pluginsConfig) {
 		await setup({
 			config: pluginsUserConfig ? { ...userConfig, plugins: pluginsUserConfig } : userConfig,
 			updateConfig(newConfig) {
@@ -52,14 +48,11 @@ export async function runPlugins(
 
 				// If the plugin is updating the user config, re-validate it.
 				const mergedUserConfig = { ...userConfig, ...newConfig };
-				const mergedConfig = StarlightConfigSchema.safeParse(mergedUserConfig, { errorMap });
-
-				if (!mergedConfig.success) {
-					throwValidationError(
-						mergedConfig.error,
-						`Invalid config update provided by the '${name}' plugin`
-					);
-				}
+				const mergedConfig = parseWithFriendlyErrors(
+					StarlightConfigSchema,
+					mergedUserConfig,
+					`Invalid config update provided by the '${name}' plugin`
+				);
 
 				// If the updated config is valid, keep track of both the user config and parsed config.
 				userConfig = mergedUserConfig;
@@ -79,7 +72,7 @@ export async function runPlugins(
 		});
 	}
 
-	return { integrations, starlightConfig: starlightConfig.data };
+	return { integrations, starlightConfig };
 }
 
 // https://github.com/withastro/astro/blob/910eb00fe0b70ca80bd09520ae100e8c78b675b5/packages/astro/src/core/config/schema.ts#L113

package/utils/starlight-page.ts

@@ -1,7 +1,7 @@
 import { z } from 'astro/zod';
 import { type ContentConfig, type SchemaContext } from 'astro:content';
 import config from 'virtual:starlight/user-config';
-import { errorMap, throwValidationError } from './error-map';
+import { parseWithFriendlyErrors } from './error-map';
 import { stripLeadingAndTrailingSlashes } from './path';
 import { getToC, type PageProps, type StarlightRouteData } from './route-data';
 import type { StarlightDocsEntry } from './routing';
@@ -9,6 +9,8 @@ import { slugToLocaleData, urlToSlug } from './slugs';
 import { getPrevNextLinks, getSidebar } from './navigation';
 import { useTranslations } from './translations';
 import { docsSchema } from '../schema';
+import { BadgeConfigSchema } from '../schemas/badge';
+import { SidebarLinkItemHTMLAttributesSchema } from '../schemas/sidebar';
 
 /**
  * The frontmatter schema for Starlight pages derived from the default schema for Starlight’s
@@ -56,6 +58,93 @@ type StarlightPageFrontmatter = Omit<
 	'editUrl' | 'sidebar'
 > & { editUrl?: string | false };
 
+/**
+ * Link configuration schema for `<StarlightPage>`.
+ * Sets default values where possible to be more user friendly than raw `SidebarEntry` type.
+ */
+const LinkSchema = z
+	.object({
+		/** @deprecated Specifying `type` is no longer required. */
+		type: z.literal('link').default('link'),
+		label: z.string(),
+		href: z.string(),
+		isCurrent: z.boolean().default(false),
+		badge: BadgeConfigSchema(),
+		attrs: SidebarLinkItemHTMLAttributesSchema(),
+	})
+	// Make sure badge is in the object even if undefined — Zod doesn’t seem to have a way to set `undefined` as a default.
+	.transform((item) => ({ badge: undefined, ...item }));
+
+/** Base schema for link groups without the recursive `items` array. */
+const LinkGroupBase = z.object({
+	/** @deprecated Specifying `type` is no longer required. */
+	type: z.literal('group').default('group'),
+	label: z.string(),
+	collapsed: z.boolean().default(false),
+	badge: BadgeConfigSchema(),
+});
+
+//  These manual types are needed to correctly type the recursive link group type.
+type ManualLinkGroupInput = Prettify<
+	z.input<typeof LinkGroupBase> &
+		// The original implementation of `<StarlightPage>` in v0.19.0 used `entries`.
+		// We want to use `items` so it matches the sidebar config in `astro.config.mjs`.
+		// Keeping `entries` support for now to not break anyone.
+		// TODO: warn about `entries` usage in a future version
+		// TODO: remove support for `entries` in a future version
+		(| {
+					/** Array of links and subcategories to display in this category. */
+					items: Array<z.input<typeof LinkSchema> | ManualLinkGroupInput>;
+			  }
+			| {
+					/**
+					 * @deprecated Use `items` instead of `entries`.
+					 * Support for `entries` will be removed in a future version of Starlight.
+					 */
+					entries: Array<z.input<typeof LinkSchema> | ManualLinkGroupInput>;
+			  }
+		)
+>;
+type ManualLinkGroupOutput = z.output<typeof LinkGroupBase> & {
+	entries: Array<z.output<typeof LinkSchema> | ManualLinkGroupOutput>;
+	badge: z.output<typeof LinkGroupBase>['badge'];
+};
+type LinkGroupSchemaType = z.ZodType<ManualLinkGroupOutput, z.ZodTypeDef, ManualLinkGroupInput>;
+/**
+ * Link group configuration schema for `<StarlightPage>`.
+ * Sets default values where possible to be more user friendly than raw `SidebarEntry` type.
+ */
+const LinkGroupSchema: LinkGroupSchemaType = z.preprocess(
+	// Map `items` to `entries` as expected by the `SidebarEntry` type.
+	(arg) => {
+		if (arg && typeof arg === 'object' && 'items' in arg) {
+			const { items, ...rest } = arg;
+			return { ...rest, entries: items };
+		}
+		return arg;
+	},
+	LinkGroupBase.extend({
+		entries: z.lazy(() => z.union([LinkSchema, LinkGroupSchema]).array()),
+	})
+		// Make sure badge is in the object even if undefined.
+		.transform((item) => ({ badge: undefined, ...item }))
+) as LinkGroupSchemaType;
+
+/** Sidebar configuration schema for `<StarlightPage>` */
+const StarlightPageSidebarSchema = z.union([LinkSchema, LinkGroupSchema]).array();
+type StarlightPageSidebarUserConfig = z.input<typeof StarlightPageSidebarSchema>;
+
+/** Parse sidebar prop to ensure all required defaults are in place. */
+const normalizeSidebarProp = (
+	sidebarProp: StarlightPageSidebarUserConfig
+): StarlightRouteData['sidebar'] => {
+	return parseWithFriendlyErrors(
+		StarlightPageSidebarSchema,
+		sidebarProp,
+		'Invalid sidebar prop passed to the `<StarlightPage/>` component.'
+	);
+};
+
 /**
  * The props accepted by the `<StarlightPage/>` component.
  */
@@ -63,7 +152,8 @@ export type StarlightPageProps = Prettify<
 	// Remove the index signature from `Route`, omit undesired properties and make the rest optional.
 	Partial<Omit<RemoveIndexSignature<PageProps>, 'entry' | 'entryMeta' | 'id' | 'locale' | 'slug'>> &
 		// Add the sidebar definitions for a Starlight page.
-		Partial<Pick<StarlightRouteData, 'hasSidebar' | 'sidebar'>> & {
+		Partial<Pick<StarlightRouteData, 'hasSidebar'>> & {
+			sidebar?: StarlightPageSidebarUserConfig;
 			// And finally add the Starlight page frontmatter properties in a `frontmatter` property.
 			frontmatter: StarlightPageFrontmatter;
 		}
@@ -94,7 +184,9 @@ export async function generateStarlightPageRouteData({
 	const pageFrontmatter = await getStarlightPageFrontmatter(frontmatter);
 	const id = `${stripLeadingAndTrailingSlashes(slug)}.md`;
 	const localeData = slugToLocaleData(slug);
-	const sidebar = props.sidebar ?? getSidebar(url.pathname, localeData.locale);
+	const sidebar = props.sidebar
+		? normalizeSidebarProp(props.sidebar)
+		: getSidebar(url.pathname, localeData.locale);
 	const headings = props.headings ?? [];
 	const pageDocsEntry: StarlightPageDocsEntry = {
 		id,
@@ -172,16 +264,11 @@ async function getStarlightPageFrontmatter(frontmatter: StarlightPageFrontmatter
 			}),
 	});
 
-	const pageFrontmatter = schema.safeParse(frontmatter, { errorMap });
-
-	if (!pageFrontmatter.success) {
-		throwValidationError(
-			pageFrontmatter.error,
-			'Invalid frontmatter props passed to the `<StarlightPage/>` component.'
-		);
-	}
-
-	return pageFrontmatter.data;
+	return parseWithFriendlyErrors(
+		schema,
+		frontmatter,
+		'Invalid frontmatter props passed to the `<StarlightPage/>` component.'
+	);
 }
 
 /** Returns the user docs schema and falls back to the default schema if needed. */