@astrojs/starlight 0.41.11 → 0.42.0

package/dist/utils/slugs.js

@@ -0,0 +1,104 @@
+import { stripTrailingSlash } from "./path.js";
+import { BuiltInDefaultLocale } from "./i18n.js";
+import { slugToLocale as slugToLocale$1 } from "../integrations/shared/slugToLocale.js";
+import config from "virtual:starlight/user-config";
+//#region src/utils/slugs.ts
+/**
+* Get the “locale” of a slug. This is the base path at which a language is served.
+* For example, if French docs are in `src/content/docs/french/`, the locale is `french`.
+* Root locale slugs will return `undefined`.
+* @param slug A collection entry slug
+*/
+function slugToLocale(slug) {
+	return slugToLocale$1(slug, config);
+}
+/** Get locale information for a given slug. */
+function slugToLocaleData(slug) {
+	const locale = slugToLocale(slug);
+	return {
+		dir: localeToDir(locale),
+		lang: localeToLang(locale),
+		locale
+	};
+}
+/**
+* Get the BCP-47 language tag for the given locale.
+* @param locale Locale string or `undefined` for the root locale.
+*/
+function localeToLang(locale) {
+	const lang = locale ? config.locales?.[locale]?.lang : config.locales?.root?.lang;
+	const defaultLang = config.defaultLocale?.lang || config.defaultLocale?.locale;
+	return lang || defaultLang || BuiltInDefaultLocale.lang;
+}
+/**
+* Get the configured writing direction for the given locale.
+* @param locale Locale string or `undefined` for the root locale.
+*/
+function localeToDir(locale) {
+	return (locale ? config.locales?.[locale]?.dir : config.locales?.root?.dir) || config.defaultLocale.dir;
+}
+/**
+* Convert a content collection slug to a param as expected by Astro’s router.
+* This utility handles stripping `index` from file names and matches
+* [Astro’s param sanitization logic](https://github.com/withastro/astro/blob/687d25365a41ff8a9e6da155d3527f841abb70dd/packages/astro/src/core/routing/manifest/generator.ts#L4-L18)
+* by normalizing strings to their canonical representations.
+* @param slug Content collection slug
+* @returns Param compatible with Astro’s router
+*/
+function slugToParam(slug) {
+	return slug === "index" || slug === "" || slug === "/" ? void 0 : (slug.endsWith("/index") ? slug.slice(0, -6) : slug).normalize();
+}
+function slugToPathname(slug) {
+	const param = slugToParam(slug);
+	return param ? "/" + param + "/" : "/";
+}
+/**
+* Convert a slug to a different locale.
+* For example, passing a slug of `en/home` and a locale of `fr` results in `fr/home`.
+* An undefined locale is treated as the root locale, resulting in `home`
+* @param slug A collection entry slug
+* @param locale The target locale
+* @example
+* localizedSlug('en/home', 'fr')       // => 'fr/home'
+* localizedSlug('en/home', undefined)  // => 'home'
+*/
+function localizedSlug(slug, locale) {
+	const slugLocale = slugToLocale(slug);
+	if (slugLocale === locale) return slug;
+	locale = locale || "";
+	if (slugLocale === slug) return locale;
+	if (slugLocale) return stripTrailingSlash(slug.replace(slugLocale + "/", locale ? locale + "/" : ""));
+	return slug ? locale + "/" + slug : locale;
+}
+/**
+* Convert a file path relative to the collection root to a different locale.
+* For example, passing a file path of `en/home.md` and a locale of `fr` results in `fr/home.md`.
+* An undefined locale is treated as the root locale, resulting in `home.md`.
+* @param filePath A collection entry file path relative to the collection root
+* @param locale The target locale
+* @example
+* localizedFilePath('en/home.md', 'fr')       // => 'fr/home.md'
+* localizedFilePath('en/home.md', undefined)  // => 'home.md'
+*/
+function localizedFilePath(filePath, locale) {
+	const filePathLocale = slugToLocale(filePath);
+	if (filePathLocale) return filePath.replace(filePathLocale + "/", locale ? locale + "/" : "");
+	else if (locale) return locale + "/" + filePath;
+	else return filePath;
+}
+/** Extract the slug from a URL. */
+function urlToSlug(url) {
+	let pathname = url.pathname;
+	const base = stripTrailingSlash(import.meta.env.BASE_URL);
+	if (pathname.startsWith(base)) pathname = pathname.replace(base, "");
+	const segments = pathname.split("/");
+	const htmlExt = ".html";
+	if (segments.at(-1) === "index.html") segments.pop();
+	else if (segments.at(-1)?.endsWith(htmlExt)) {
+		const last = segments.pop();
+		if (last) segments.push(last.slice(0, -5));
+	}
+	return segments.filter(Boolean).join("/");
+}
+//#endregion
+export { localeToLang, localizedFilePath, localizedSlug, slugToLocaleData, slugToParam, slugToPathname, urlToSlug };

package/dist/utils/starlight-page.d.ts

@@ -0,0 +1,36 @@
+import { Prettify, RemoveIndexSignature } from "./types.js";
+import { StarlightUserConfig } from "./user-config.js";
+import { StarlightRouteData } from "./routing/types.js";
+import { PageProps, RouteDataContext } from "./routing/data.js";
+import { z } from "astro/zod";
+import { SchemaContext } from "astro:content";
+//#region src/utils/starlight-page.d.ts
+/**
+ * The frontmatter schema for Starlight pages derived from the default schema for Starlight’s
+ * `docs` content collection.
+ * The frontmatter schema for Starlight pages cannot include some properties which will be omitted
+ * and some others needs to be refined to a stricter type.
+ */
+declare const StarlightPageFrontmatterSchema: (context: SchemaContext) => Promise<any>;
+/**
+ * Type of Starlight pages frontmatter schema.
+ * We manually refines the `editUrl` type and omit the `sidebar` property as it's not possible to
+ * do that on the schema itself using Zod but the proper validation is still using a transformer.
+ * @see StarlightPageFrontmatterSchema
+ */
+type StarlightPageFrontmatter = Omit<z.input<Awaited<ReturnType<typeof StarlightPageFrontmatterSchema>>>, 'editUrl' | 'sidebar'> & {
+  editUrl?: string | false;
+};
+/**
+ * The props accepted by the `<StarlightPage/>` component.
+ */
+type StarlightPageProps = Prettify<Partial<Omit<RemoveIndexSignature<PageProps>, 'entry' | 'entryMeta' | 'id' | 'locale'>> & Partial<Pick<StarlightRouteData, 'hasSidebar'>> & {
+  sidebar?: StarlightUserConfig['sidebar'];
+  frontmatter: StarlightPageFrontmatter;
+}>;
+declare function generateStarlightPageRouteData({ props, context }: {
+  props: StarlightPageProps;
+  context: RouteDataContext;
+}): Promise<StarlightRouteData>;
+//#endregion
+export { StarlightPageProps, generateStarlightPageRouteData };

package/dist/utils/starlight-page.js

@@ -0,0 +1,120 @@
+import { getCollectionPathFromRoot } from "./collection.js";
+import { stripLeadingAndTrailingSlashes } from "./path.js";
+import { parseAsyncWithFriendlyErrors, parseWithFriendlyErrors } from "./error-map.js";
+import { SidebarItemSchema } from "../schemas/sidebar.js";
+import { docsSchema } from "../schema.js";
+import { getHead } from "./head.js";
+import { slugToLocaleData, urlToSlug } from "./slugs.js";
+import { getPrevNextLinks, getSidebar, getSidebarFromConfig } from "./navigation.js";
+import { getSiteTitle, getSiteTitleHref, getToC } from "./routing/data.js";
+import { z } from "astro/zod";
+import "astro:content";
+import config from "virtual:starlight/user-config";
+import project from "virtual:starlight/project-context";
+//#region src/utils/starlight-page.ts
+/**
+* The frontmatter schema for Starlight pages derived from the default schema for Starlight’s
+* `docs` content collection.
+* The frontmatter schema for Starlight pages cannot include some properties which will be omitted
+* and some others needs to be refined to a stricter type.
+*/
+const StarlightPageFrontmatterSchema = async (context) => {
+	const userDocsSchema = await getUserDocsSchema();
+	return (typeof userDocsSchema === "function" ? userDocsSchema(context) : userDocsSchema).transform((frontmatter) => {
+		/**
+		* Starlight pages can only be edited if an edit URL is explicitly provided.
+		* The `sidebar` frontmatter prop only works for pages in an autogenerated links group.
+		* Starlight pages edit links cannot be autogenerated.
+		*
+		* These changes to the schema are done using a transformer and not using the usual `omit`
+		* method because when the frontmatter schema is extended by the user, an intersection between
+		* the default schema and the user schema is created using the `and` method. Intersections in
+		* Zod returns a `ZodIntersection` object which does not have some methods like `omit` or
+		* `pick`.
+		*
+		* This transformer only sets the `editUrl` default value and removes the `sidebar` property
+		* from the validated output but does not apply any changes to the input schema type itself so
+		* this needs to be done manually.
+		*
+		* @see StarlightPageFrontmatter
+		* @see https://github.com/colinhacks/zod#intersections
+		*/
+		const { editUrl, sidebar, ...others } = frontmatter;
+		const pageEditUrl = editUrl === void 0 || editUrl === true ? false : editUrl;
+		return {
+			...others,
+			editUrl: pageEditUrl
+		};
+	});
+};
+/** Parse sidebar prop to ensure it's valid. */
+const validateSidebarProp = (sidebarProp) => {
+	return parseWithFriendlyErrors(SidebarItemSchema.array().optional(), sidebarProp, "Invalid sidebar prop passed to the `<StarlightPage/>` component.");
+};
+async function generateStarlightPageRouteData({ props, context }) {
+	const { frontmatter, ...routeProps } = props;
+	const { url } = context;
+	const id = urlToSlug(url);
+	const pageFrontmatter = await getStarlightPageFrontmatter(frontmatter);
+	const localeData = slugToLocaleData(id);
+	const sidebar = props.sidebar ? getSidebarFromConfig(validateSidebarProp(props.sidebar), url.pathname, localeData.locale) : getSidebar(url.pathname, localeData.locale);
+	const headings = props.headings ?? [];
+	const entry = {
+		id,
+		body: "",
+		collection: "docs",
+		filePath: `${getCollectionPathFromRoot("docs", project)}/${stripLeadingAndTrailingSlashes(id)}.md`,
+		data: {
+			...pageFrontmatter,
+			sidebar: {
+				attrs: {},
+				hidden: false
+			}
+		}
+	};
+	const entryMeta = {
+		dir: props.dir ?? localeData.dir,
+		lang: props.lang ?? localeData.lang,
+		locale: localeData.locale
+	};
+	const editUrl = pageFrontmatter.editUrl ? new URL(pageFrontmatter.editUrl) : void 0;
+	const lastUpdated = pageFrontmatter.lastUpdated instanceof Date ? pageFrontmatter.lastUpdated : void 0;
+	const pageProps = {
+		...routeProps,
+		...localeData,
+		entry,
+		entryMeta,
+		headings,
+		id,
+		locale: localeData.locale
+	};
+	const siteTitle = getSiteTitle(localeData.lang);
+	return {
+		...routeProps,
+		...localeData,
+		id,
+		editUrl,
+		entry,
+		entryMeta,
+		hasSidebar: props.hasSidebar ?? entry.data.template !== "splash",
+		head: getHead(pageProps, context, siteTitle),
+		headings,
+		lastUpdated,
+		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
+		sidebar,
+		siteTitle,
+		siteTitleHref: getSiteTitleHref(localeData.locale),
+		toc: getToC(pageProps)
+	};
+}
+/** Validates the Starlight page frontmatter properties from the props received by a Starlight page. */
+async function getStarlightPageFrontmatter(frontmatter) {
+	const schema = await StarlightPageFrontmatterSchema({ image: (() => z.custom((value) => value && (typeof value === "function" || typeof value === "object") && "src" in value && "width" in value && "height" in value && "format" in value, "Invalid image passed to `<StarlightPage>` component. Expected imported `ImageMetadata` object.")) });
+	return parseAsyncWithFriendlyErrors(schema, frontmatter, "Invalid frontmatter props passed to the `<StarlightPage/>` component.");
+}
+/** Returns the user docs schema and falls back to the default schema if needed. */
+async function getUserDocsSchema() {
+	return (await import("virtual:starlight/collection-config")).collections?.docs?.schema ?? docsSchema();
+}
+//#endregion
+export { generateStarlightPageRouteData };

package/dist/utils/translations-fs.d.ts

@@ -0,0 +1,15 @@
+import { StarlightConfig } from "./user-config.js";
+import { i18nSchemaOutput } from "../schemas/i18n.js";
+import { I18nT } from "./createTranslationSystem.js";
+import { AstroConfig } from "astro";
+//#region src/utils/translations-fs.d.ts
+/**
+ * Loads and creates a translation system from the file system.
+ * Only for use in integration code.
+ * In modules loaded by Vite/Astro, import [`useTranslations`](./translations.ts) instead.
+ *
+ * @see [`./translations.ts`](./translations.ts)
+ */
+declare function createTranslationSystemFromFs<T extends i18nSchemaOutput>(opts: Pick<StarlightConfig, 'defaultLocale' | 'locales'>, { srcDir }: Pick<AstroConfig, 'srcDir'>, pluginTranslations?: Record<string, T>): Promise<(lang: string | undefined) => I18nT>;
+//#endregion
+export { createTranslationSystemFromFs };

package/dist/utils/translations-fs.js

@@ -0,0 +1,39 @@
+import { createTranslationSystem } from "./createTranslationSystem.js";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+import yaml from "js-yaml";
+//#region src/utils/translations-fs.ts
+const contentCollectionFileExtensions = [
+	".json",
+	".yaml",
+	".yml"
+];
+/**
+* Loads and creates a translation system from the file system.
+* Only for use in integration code.
+* In modules loaded by Vite/Astro, import [`useTranslations`](./translations.ts) instead.
+*
+* @see [`./translations.ts`](./translations.ts)
+*/
+async function createTranslationSystemFromFs(opts, { srcDir }, pluginTranslations = {}) {
+	/** All translation data from the i18n collection, keyed by `id`, which matches locale. */
+	const userTranslations = {};
+	try {
+		const i18nDir = new URL("content/i18n/", srcDir);
+		const files = fs.readdirSync(i18nDir, "utf-8");
+		for (const file of files) {
+			const filePath = path.parse(file);
+			if (!contentCollectionFileExtensions.includes(filePath.ext)) continue;
+			const id = filePath.name;
+			const url = new URL(filePath.base, i18nDir);
+			const content = fs.readFileSync(new URL(file, i18nDir), "utf-8");
+			userTranslations[id] = filePath.ext === ".json" ? JSON.parse(content) : yaml.load(content, { filename: fileURLToPath(url) });
+		}
+	} catch (e) {
+		if (e instanceof Error && "code" in e && e.code === "ENOENT") {} else throw e;
+	}
+	return createTranslationSystem(opts, userTranslations, pluginTranslations);
+}
+//#endregion
+export { createTranslationSystemFromFs };

package/dist/utils/translations.d.ts

@@ -0,0 +1,20 @@
+import { RemoveIndexSignature } from "./types.js";
+import { i18nSchemaOutput } from "../schemas/i18n.js";
+import { I18nT } from "./createTranslationSystem.js";
+import { CollectionEntry, DataCollectionKey } from "astro:content";
+//#region src/utils/translations.d.ts
+type i18nCollection = CollectionEntry<'i18n'>;
+type UserI18nSchema = 'i18n' extends DataCollectionKey ? i18nCollection extends {
+  data: infer T;
+} ? i18nSchemaOutput & T : i18nSchemaOutput : i18nSchemaOutput;
+type UserI18nKeys = keyof RemoveIndexSignature<UserI18nSchema>;
+/**
+ * Generate a utility function that returns UI strings for the given language.
+ * @param {string | undefined} [lang]
+ * @example
+ * const t = useTranslations('en');
+ * const label = t('search.label'); // => 'Search'
+ */
+declare const useTranslations: (lang: string | undefined) => I18nT;
+//#endregion
+export { UserI18nKeys, UserI18nSchema, useTranslations };

package/dist/utils/translations.js

@@ -0,0 +1,29 @@
+import { getCollectionPathFromRoot } from "./collection.js";
+import { stripExtension, stripLeadingSlash } from "./path.js";
+import { createTranslationSystem } from "./createTranslationSystem.js";
+import { getCollection } from "astro:content";
+import config from "virtual:starlight/user-config";
+import project from "virtual:starlight/project-context";
+import pluginTranslations from "virtual:starlight/plugin-translations";
+//#region src/utils/translations.ts
+const i18nCollectionPathFromRoot = getCollectionPathFromRoot("i18n", project);
+/** Get all translation data from the i18n collection, keyed by `lang`, which are BCP-47 language tags. */
+async function loadTranslations() {
+	const warn = console.warn;
+	console.warn = () => {};
+	const userTranslations = Object.fromEntries((await getCollection("i18n")).map(({ id, data, filePath }) => {
+		return [!filePath ? id : stripExtension(stripLeadingSlash(filePath.replace(i18nCollectionPathFromRoot, ""))), data];
+	}));
+	console.warn = warn;
+	return userTranslations;
+}
+/**
+* Generate a utility function that returns UI strings for the given language.
+* @param {string | undefined} [lang]
+* @example
+* const t = useTranslations('en');
+* const label = t('search.label'); // => 'Search'
+*/
+const useTranslations = await createTranslationSystem(config, await loadTranslations(), pluginTranslations);
+//#endregion
+export { useTranslations };

package/dist/utils/types.d.ts

@@ -0,0 +1,5 @@
+//#region src/utils/types.d.ts
+type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: T[K]; };
+type Prettify<T> = { [K in keyof T]: T[K]; } & {};
+//#endregion
+export { Prettify, RemoveIndexSignature };

package/dist/utils/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/url.d.ts

@@ -0,0 +1,7 @@
+//#region src/utils/url.d.ts
+/** Check if a string starts with one of `http://` or `https://`. */
+declare const isAbsoluteUrl: (link: string) => boolean;
+/** Check if a string contains a protocol (e.g., `http:`, `https:`, `mailto:`). */
+declare const hasProtocol: (link: string) => boolean;
+//#endregion
+export { hasProtocol, isAbsoluteUrl };

package/{utils/url.ts → dist/utils/url.js}

@@ -1,8 +1,9 @@
+//#region src/utils/url.ts
 const HTTPProtocolRegEx = /^https?:\/\//;
 const ProtocolRegEx = /^[a-z][a-z\d+.-]*:/i;
-
 /** Check if a string starts with one of `http://` or `https://`. */
-export const isAbsoluteUrl = (link: string) => HTTPProtocolRegEx.test(link);
-
+const isAbsoluteUrl = (link) => HTTPProtocolRegEx.test(link);
 /** Check if a string contains a protocol (e.g., `http:`, `https:`, `mailto:`). */
-export const hasProtocol = (link: string) => ProtocolRegEx.test(link);
+const hasProtocol = (link) => ProtocolRegEx.test(link);
+//#endregion
+export { hasProtocol, isAbsoluteUrl };