@astrojs/starlight 0.41.11 → 0.42.0

package/dist/utils/error-map.js

@@ -0,0 +1,125 @@
+import { AstroError } from "astro/errors";
+import { locales } from "astro/zod";
+//#region src/utils/error-map.ts
+/**
+* This is a modified version of Astro's error map.
+* source: https://github.com/withastro/astro/blob/main/packages/astro/src/content/error-map.ts
+*/
+const zodErrorMap = locales.en().localeError;
+/**
+* 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.
+*/
+function parseWithFriendlyErrors(schema, input, message) {
+	return processParsedData(schema.safeParse(input, {
+		error: errorMap,
+		reportInput: true
+	}), message);
+}
+/**
+* Asynchronously parse data with a Zod schema that contains asynchronous refinements or transforms
+* 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.
+*/
+async function parseAsyncWithFriendlyErrors(schema, input, message) {
+	return processParsedData(await schema.safeParseAsync(input, {
+		error: errorMap,
+		reportInput: true
+	}), message);
+}
+function processParsedData(parsedData, message) {
+	if (!parsedData.success) throw new AstroError(message, parsedData.error.issues.map((i) => i.message).join("\n"));
+	return parsedData.data;
+}
+const errorMap = (issue) => {
+	const baseErrorPath = flattenErrorPath(issue.path ?? []);
+	if (issue.code === "invalid_union") {
+		const unionErrors = issue.errors.flat();
+		const typeOrLiteralErrByPath = /* @__PURE__ */ new Map();
+		for (const unionError of unionErrors) if (unionError.code === "invalid_type") {
+			const flattenedErrorPath = flattenErrorPath([baseErrorPath, ...unionError.path]);
+			if (typeOrLiteralErrByPath.has(flattenedErrorPath)) typeOrLiteralErrByPath.get(flattenedErrorPath).expected.push(unionError.expected);
+			else typeOrLiteralErrByPath.set(flattenedErrorPath, {
+				code: unionError.code,
+				received: parsedType(issue.input),
+				expected: [unionError.expected],
+				message: unionError.message
+			});
+		}
+		const messages = [prefix(baseErrorPath, "Did not match union.")];
+		const details = [...typeOrLiteralErrByPath.entries()].filter(([, error]) => error.expected.length === unionErrors.length).map(([key, error]) => key === baseErrorPath ? `> ${getTypeErrMsg(error)}` : `> ${prefix(key, getTypeErrMsg(error))}`);
+		if (details.length === 0) {
+			const expectedShapes = [];
+			for (const unionError of issue.errors) {
+				const expectedShape = [];
+				for (const issue of unionError) {
+					if (issue.code === "invalid_type" && issue.expected === "never") continue;
+					if (issue.code === "invalid_union") return errorMap({
+						...issue,
+						input: issue.input,
+						path: [baseErrorPath, ...issue.path]
+					});
+					const relativePath = flattenErrorPath(issue.path).replace(baseErrorPath, "").replace(leadingPeriod, "");
+					if (issue.code === "invalid_type") expectedShape.push(relativePath ? `${relativePath}: ${issue.expected}` : issue.expected);
+					else if (issue.code === "custom") expectedShape.push(relativePath);
+				}
+				if (expectedShape.length === 1 && !expectedShape[0]?.includes(":")) expectedShapes.push(expectedShape.join(""));
+				else if (expectedShape.length > 0) expectedShapes.push(`{ ${expectedShape.join("; ")} }`);
+			}
+			if (expectedShapes.length) {
+				details.push("> Expected type `" + expectedShapes.join(" | ") + "`");
+				details.push("> Received `" + stringify(issue.input) + "`");
+			}
+		}
+		return messages.concat(details).join("\n");
+	} else if (issue.code === "invalid_type") return prefix(baseErrorPath, getTypeErrMsg({
+		code: issue.code,
+		received: parsedType(issue.input),
+		expected: [issue.expected],
+		message: issue.message
+	}));
+	else if (issue.message) return prefix(baseErrorPath, issue.message);
+	else {
+		const defaultError = zodErrorMap(issue);
+		if (!defaultError) return;
+		return prefix(baseErrorPath, typeof defaultError === "string" ? defaultError : defaultError.message);
+	}
+};
+const getTypeErrMsg = (error) => {
+	if (typeof error.received === "undefined" || error.received === "undefined") return error.message ?? "Required";
+	const expectedDeduped = new Set(error.expected);
+	return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(error.received)}\``;
+};
+const prefix = (key, msg) => key.length ? `**${key}**: ${msg}` : msg;
+const unionExpectedVals = (expectedVals) => [...expectedVals].map((expectedVal) => stringify(expectedVal)).join(" | ");
+const flattenErrorPath = (errorPath) => errorPath.join(".");
+/** `JSON.stringify()` a value with spaces around object/array entries. */
+const stringify = (val) => JSON.stringify(val, null, 1).split(newlinePlusWhitespace).join(" ");
+const newlinePlusWhitespace = /\n\s*/;
+const leadingPeriod = /^\./;
+/**
+* In Zod 4, we don't necessarily get a human-readable representation of input data types. For such
+* cases, we use the same logic as Zod's own `parsedType()` function.
+* @see https://github.com/colinhacks/zod/blob/73b071d7d08825dedb6b48b78718739118ee1308/packages/zod/src/v4/locales/en.ts#L5
+*/
+const parsedType = (data) => {
+	const t = typeof data;
+	switch (t) {
+		case "number": return Number.isNaN(data) ? "NaN" : "number";
+		case "object":
+			if (Array.isArray(data)) return "array";
+			if (data === null) return "null";
+			if (data && Object.getPrototypeOf(data) !== Object.prototype && data.constructor) return data.constructor.name;
+	}
+	return t;
+};
+//#endregion
+export { parseAsyncWithFriendlyErrors, parseWithFriendlyErrors };

package/dist/utils/format-path.d.ts

@@ -0,0 +1,4 @@
+//#region src/utils/format-path.d.ts
+declare const formatPath: (href: string) => string;
+//#endregion
+export { formatPath };

package/dist/utils/format-path.js

@@ -0,0 +1,9 @@
+import { createPathFormatter } from "./createPathFormatter.js";
+import project from "virtual:starlight/project-context";
+//#region src/utils/format-path.ts
+const formatPath = createPathFormatter({
+	format: project.build.format,
+	trailingSlash: project.trailingSlash
+});
+//#endregion
+export { formatPath };

package/dist/utils/generateToC.d.ts

@@ -0,0 +1,14 @@
+import { MarkdownHeading } from "astro";
+//#region src/utils/generateToC.d.ts
+interface TocItem extends MarkdownHeading {
+  children: TocItem[];
+}
+interface TocOpts {
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+  title: string;
+}
+/** Convert the flat headings array generated by Astro into a nested tree structure. */
+declare function generateToC(headings: MarkdownHeading[], { minHeadingLevel, maxHeadingLevel, title }: TocOpts): TocItem[];
+//#endregion
+export { TocItem, generateToC };

package/dist/utils/generateToC.js

@@ -0,0 +1,25 @@
+import { PAGE_TITLE_ID } from "../constants.js";
+//#region src/utils/generateToC.ts
+/** Convert the flat headings array generated by Astro into a nested tree structure. */
+function generateToC(headings, { minHeadingLevel, maxHeadingLevel, title }) {
+	headings = headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel);
+	const toc = [{
+		depth: 2,
+		slug: PAGE_TITLE_ID,
+		text: title,
+		children: []
+	}];
+	for (const heading of headings) injectChild(toc, {
+		...heading,
+		children: []
+	});
+	return toc;
+}
+/** Inject a ToC entry as deep in the tree as its `depth` property requires. */
+function injectChild(items, item) {
+	const lastItem = items.at(-1);
+	if (!lastItem || lastItem.depth >= item.depth) items.push(item);
+	else return injectChild(lastItem.children, item);
+}
+//#endregion
+export { generateToC };

package/dist/utils/git.d.ts

@@ -0,0 +1,12 @@
+//#region src/utils/git.d.ts
+/**
+ * Git module to be used from the dev server and from the integration.
+ */
+type GitAPI = {
+  getNewestCommitDate: (file: string) => Date;
+};
+declare const makeAPI: (directory: string) => GitAPI;
+declare function getNewestCommitDate(file: string): Date;
+declare function getAllNewestCommitDate(rootPath: string, docsPath: string): [string, number][];
+//#endregion
+export { GitAPI, getAllNewestCommitDate, getNewestCommitDate, makeAPI };

package/dist/utils/git.js

@@ -0,0 +1,71 @@
+import { basename, dirname, relative, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+//#region src/utils/git.ts
+/**
+* Git module to be used from the dev server and from the integration.
+*/
+const makeAPI = (directory) => {
+	return { getNewestCommitDate: (file) => getNewestCommitDate(resolve(directory, file)) };
+};
+function getNewestCommitDate(file) {
+	const result = spawnSync("git", [
+		"log",
+		"--format=%ct",
+		"--max-count=1",
+		basename(file)
+	], {
+		cwd: dirname(file),
+		encoding: "utf-8"
+	});
+	if (result.error) throw new Error(`Failed to retrieve the git history for file "${file}"`);
+	const match = result.stdout.trim().match(/^(?<timestamp>\d+)$/);
+	if (!match?.groups?.timestamp) throw new Error(`Failed to validate the timestamp for file "${file}"`);
+	const timestamp = Number(match.groups.timestamp);
+	return /* @__PURE__ */ new Date(timestamp * 1e3);
+}
+function getRepoRoot(directory) {
+	const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+		cwd: directory,
+		encoding: "utf-8"
+	});
+	if (result.error) return directory;
+	try {
+		return realpathSync(result.stdout.trim());
+	} catch {
+		return directory;
+	}
+}
+function getAllNewestCommitDate(rootPath, docsPath) {
+	const repoRoot = getRepoRoot(docsPath);
+	const gitLog = spawnSync("git", [
+		"log",
+		"--format=t:%ct",
+		"--name-status",
+		"--",
+		docsPath
+	], {
+		cwd: repoRoot,
+		encoding: "utf-8",
+		maxBuffer: 10485760
+	});
+	if (gitLog.error) return [];
+	let runningDate = Date.now();
+	const latestDates = /* @__PURE__ */ new Map();
+	for (const logLine of gitLog.stdout.split("\n")) {
+		if (logLine.startsWith("t:")) runningDate = Number.parseInt(logLine.slice(2)) * 1e3;
+		const tabSplit = logLine.lastIndexOf("	");
+		if (tabSplit === -1) continue;
+		const fileName = logLine.slice(tabSplit + 1);
+		const currentLatest = latestDates.get(fileName) || 0;
+		latestDates.set(fileName, Math.max(currentLatest, runningDate));
+	}
+	return Array.from(latestDates.entries()).map(([file, date]) => {
+		const fileFullPath = resolve(repoRoot, file);
+		let fileInDirectory = relative(rootPath, fileFullPath);
+		fileInDirectory = fileInDirectory?.replace(/\\/g, "/");
+		return [fileInDirectory, date];
+	});
+}
+//#endregion
+export { getAllNewestCommitDate, getNewestCommitDate, makeAPI };

package/dist/utils/gitInlined.d.ts

@@ -0,0 +1,6 @@
+import { GitAPI, getAllNewestCommitDate } from "./git.js";
+//#region src/utils/gitInlined.d.ts
+type InlinedData = ReturnType<typeof getAllNewestCommitDate>;
+declare const makeAPI: (data: InlinedData) => GitAPI;
+//#endregion
+export { makeAPI };

package/dist/utils/gitInlined.js

@@ -0,0 +1,11 @@
+//#region src/utils/gitInlined.ts
+const makeAPI = (data) => {
+	const trackedDocsFiles = new Map(data);
+	return { getNewestCommitDate: (file) => {
+		const timestamp = trackedDocsFiles.get(file);
+		if (!timestamp) throw new Error(`Failed to retrieve the git history for file "${file}"`);
+		return new Date(timestamp);
+	} };
+};
+//#endregion
+export { makeAPI };

package/dist/utils/head.d.ts

@@ -0,0 +1,7 @@
+import { HeadConfig } from "../schemas/head.js";
+import { PageProps, RouteDataContext } from "./routing/data.js";
+//#region src/utils/head.d.ts
+/** Get the head for the current page. */
+declare function getHead({ entry, lang }: PageProps, context: RouteDataContext, siteTitle: string): HeadConfig;
+//#endregion
+export { getHead };

package/dist/utils/head.js

@@ -0,0 +1,233 @@
+import { HeadConfigSchema } from "../schemas/head.js";
+import { fileWithBase } from "./base.js";
+import { formatCanonical } from "./canonical.js";
+import { version } from "../package.js";
+import { localizedUrl } from "./localizedUrl.js";
+import { isAbsoluteUrl } from "./url.js";
+import config from "virtual:starlight/user-config";
+import project from "virtual:starlight/project-context";
+//#region src/utils/head.ts
+const HeadSchema = HeadConfigSchema({ source: "content" });
+/** Get the head for the current page. */
+function getHead({ entry, lang }, context, siteTitle) {
+	const { data } = entry;
+	const canonical = context.site ? new URL(context.url.pathname, context.site) : void 0;
+	const canonicalHref = canonical?.href ? formatCanonical(canonical.href, {
+		format: project.build.format,
+		trailingSlash: project.trailingSlash
+	}) : void 0;
+	const description = data.description || config.description;
+	const headDefaults = [
+		{
+			tag: "meta",
+			attrs: { charset: "utf-8" }
+		},
+		{
+			tag: "meta",
+			attrs: {
+				name: "viewport",
+				content: "width=device-width, initial-scale=1"
+			}
+		},
+		{
+			tag: "title",
+			content: `${data.title} ${config.titleDelimiter} ${siteTitle}`
+		},
+		...canonicalHref !== void 0 ? [{
+			tag: "link",
+			attrs: {
+				rel: "canonical",
+				href: canonicalHref
+			}
+		}] : [],
+		{
+			tag: "meta",
+			attrs: {
+				name: "generator",
+				content: context.generator
+			}
+		},
+		{
+			tag: "meta",
+			attrs: {
+				name: "generator",
+				content: `Starlight v${version}`
+			}
+		},
+		{
+			tag: "link",
+			attrs: {
+				rel: "shortcut icon",
+				href: isAbsoluteUrl(config.favicon.href) ? config.favicon.href : fileWithBase(config.favicon.href),
+				type: config.favicon.type
+			}
+		},
+		{
+			tag: "meta",
+			attrs: {
+				property: "og:title",
+				content: data.title
+			}
+		},
+		{
+			tag: "meta",
+			attrs: {
+				property: "og:type",
+				content: "article"
+			}
+		},
+		...canonicalHref !== void 0 ? [{
+			tag: "meta",
+			attrs: {
+				property: "og:url",
+				content: canonicalHref
+			}
+		}] : [],
+		{
+			tag: "meta",
+			attrs: {
+				property: "og:locale",
+				content: lang
+			}
+		},
+		...description !== void 0 ? [{
+			tag: "meta",
+			attrs: {
+				property: "og:description",
+				content: description
+			}
+		}] : [],
+		{
+			tag: "meta",
+			attrs: {
+				property: "og:site_name",
+				content: siteTitle
+			}
+		},
+		{
+			tag: "meta",
+			attrs: {
+				name: "twitter:card",
+				content: "summary_large_image"
+			}
+		}
+	];
+	if (description) headDefaults.push({
+		tag: "meta",
+		attrs: {
+			name: "description",
+			content: description
+		}
+	});
+	if (canonical && config.isMultilingual) {
+		for (const locale in config.locales) {
+			const localeOpts = config.locales[locale];
+			if (!localeOpts) continue;
+			headDefaults.push({
+				tag: "link",
+				attrs: {
+					rel: "alternate",
+					hreflang: localeOpts.lang,
+					href: localizedUrl(canonical, locale, project.trailingSlash).href
+				}
+			});
+		}
+		headDefaults.push({
+			tag: "link",
+			attrs: {
+				rel: "alternate",
+				hreflang: "x-default",
+				href: localizedUrl(canonical, config.defaultLocale.locale, project.trailingSlash).href
+			}
+		});
+	}
+	if (context.site) headDefaults.push({
+		tag: "link",
+		attrs: {
+			rel: "sitemap",
+			href: fileWithBase("/sitemap-index.xml")
+		}
+	});
+	const twitterLink = config.social?.find(({ icon }) => icon === "twitter" || icon === "x.com");
+	if (twitterLink) headDefaults.push({
+		tag: "meta",
+		attrs: {
+			name: "twitter:site",
+			content: new URL(twitterLink.href).pathname.replace("/", "@")
+		}
+	});
+	return createHead(headDefaults, config.head, data.head);
+}
+/** Create a fully parsed, merged, and sorted head entry array from multiple sources. */
+function createHead(defaults, ...heads) {
+	let head = HeadSchema.parse(defaults);
+	for (const next of heads) head = mergeHead(head, next);
+	return sortHead(head);
+}
+/**
+* Test if a head config object contains a matching `<title>`, `<meta>`, `<link rel="canonical">`
+* or `<link rel="sitemap">` tag.
+*
+* For example, will return true if `head` already contains
+* `<meta name="description" content="A">` and the passed `tag`
+* is `<meta name="description" content="B">`. Tests against `name`,
+* `property`, and `http-equiv` attributes for `<meta>` tags.
+*/
+function hasTag(head, entry) {
+	switch (entry.tag) {
+		case "title": return head.some(({ tag }) => tag === "title");
+		case "meta": return hasOneOf(head, entry, [
+			"name",
+			"property",
+			"http-equiv"
+		]);
+		case "link": return head.some(({ attrs }) => entry.attrs?.rel === "canonical" && attrs?.rel === "canonical" || entry.attrs?.rel === "sitemap" && attrs?.rel === "sitemap");
+		default: return false;
+	}
+}
+/**
+* Test if a head config object contains a tag of the same type
+* as `entry` and a matching attribute for one of the passed `keys`.
+*/
+function hasOneOf(head, entry, keys) {
+	const attr = getAttr(keys, entry);
+	if (!attr) return false;
+	const [key, val] = attr;
+	return head.some(({ tag, attrs }) => tag === entry.tag && attrs?.[key] === val);
+}
+/** Find the first matching key–value pair in a head entry’s attributes. */
+function getAttr(keys, entry) {
+	let attr;
+	for (const key of keys) {
+		const val = entry.attrs?.[key];
+		if (val) {
+			attr = [key, val];
+			break;
+		}
+	}
+	return attr;
+}
+/** Merge two heads, overwriting entries in the first head that exist in the second. */
+function mergeHead(oldHead, newHead) {
+	return [...oldHead.filter((tag) => !hasTag(newHead, tag)), ...newHead];
+}
+/** Sort head tags to place important tags first and relegate “SEO” meta tags. */
+function sortHead(head) {
+	return head.sort((a, b) => {
+		const aImportance = getImportance(a);
+		const bImportance = getImportance(b);
+		return aImportance > bImportance ? -1 : bImportance > aImportance ? 1 : 0;
+	});
+}
+/** Get the relative importance of a specific head tag. */
+function getImportance(entry) {
+	if (entry.tag === "meta" && entry.attrs && ("charset" in entry.attrs || "http-equiv" in entry.attrs || entry.attrs.name === "viewport")) return 100;
+	if (entry.tag === "title") return 90;
+	if (entry.tag !== "meta") {
+		if (entry.tag === "link" && entry.attrs && "rel" in entry.attrs && entry.attrs.rel === "shortcut icon") return 70;
+		return 80;
+	}
+	return 0;
+}
+//#endregion
+export { getHead };

package/dist/utils/i18n.d.ts

@@ -0,0 +1,50 @@
+import { StarlightConfig } from "./user-config.js";
+import { AstroConfig } from "astro";
+//#region src/utils/i18n.d.ts
+/** Information about the built-in default locale used as a fallback when no locales are defined. */
+declare const BuiltInDefaultLocale: {
+  lang: string;
+  label: string;
+  dir: "rtl" | "ltr";
+};
+/**
+ * Processes the Astro and Starlight i18n configurations to generate/update them accordingly:
+ *
+ * 	- If no Astro and Starlight i18n configurations are provided, the built-in default locale is
+ * used in Starlight and the generated Astro i18n configuration will match it.
+ * 	- If only a Starlight i18n configuration is provided, an equivalent Astro i18n configuration is
+ * generated.
+ * 	- If only an Astro i18n configuration is provided, an equivalent Starlight i18n configuration is
+ * used.
+ * 	- If both an Astro and Starlight i18n configurations are provided, an error is thrown.
+ */
+declare function processI18nConfig(starlightConfig: StarlightConfig, astroI18nConfig: AstroConfig['i18n']): {
+  astroI18nConfig: {
+    defaultLocale: string;
+    locales: (string | {
+      path: string;
+      codes: [string, ...string[]];
+    })[];
+    routing: "manual" | {
+      prefixDefaultLocale: boolean;
+      redirectToDefaultLocale: boolean;
+      fallbackType: "redirect" | "rewrite";
+    };
+    domains?: Record<string, string> | undefined;
+    fallback?: Record<string, string> | undefined;
+  };
+  starlightConfig: StarlightConfig;
+};
+/**
+ * Get the string for the passed language from a dictionary object.
+ *
+ * TODO: Make this clever. Currently a simple key look-up, but should use
+ * BCP-47 mapping so that e.g. `en-US` returns `en` strings, and use the
+ * site’s default locale as a last resort.
+ *
+ * @example
+ * pickLang({ en: 'Hello', fr: 'Bonjour' }, 'en'); // => 'Hello'
+ */
+declare function pickLang<T extends Record<string, string>>(dictionary: T, lang: keyof T): string | undefined;
+//#endregion
+export { BuiltInDefaultLocale, pickLang, processI18nConfig };