@astrojs/starlight 0.41.10 → 0.42.0

package/dist/integrations/vite-layer-order.js

@@ -0,0 +1,56 @@
+import MagicString from "magic-string";
+//#region src/integrations/vite-layer-order.ts
+const pluginTransformIdIncludeFilter = /\.astro$/;
+const pluginTransformIdExcludeFilter = /@astrojs\/starlight\/components\/StarlightPage\.astro$/;
+const pluginTransformCodeFilter = "StarlightPage.astro";
+const starlightPageImportSource = "@astrojs/starlight/components/StarlightPage.astro";
+/**
+* Vite plugin that ensures the StarlightPage component is always imported first when imported in
+* an Astro file.
+*
+* This is necessary to ensure a predictable CSS layer order which is defined by the `<Page />`
+* imported by the `<StarlightPage />` component. If a user imports any other component using
+* cascade layers before the `<StarlightPage />` component, it will result in undesired layers
+* being created before we explicitly set the expected layer order.
+*/
+function vitePluginStarlightCssLayerOrder() {
+	return {
+		name: "vite-plugin-starlight-css-layer-order",
+		enforce: "pre",
+		transform: {
+			filter: {
+				id: {
+					include: pluginTransformIdIncludeFilter,
+					exclude: pluginTransformIdExcludeFilter
+				},
+				code: pluginTransformCodeFilter
+			},
+			handler(code, id) {
+				let ast;
+				try {
+					ast = this.parse(code);
+				} catch {
+					return;
+				}
+				let hasStarlightPageImport = false;
+				for (const node of ast.body) {
+					if (node.type !== "ImportDeclaration") continue;
+					if (node.source.value !== starlightPageImportSource) continue;
+					if (!node.specifiers.find((specifier) => specifier.type === "ImportDefaultSpecifier")) continue;
+					hasStarlightPageImport = true;
+					break;
+				}
+				if (!hasStarlightPageImport) return;
+				const filename = id.replace(/\\/g, "/");
+				const ms = new MagicString(code, { filename });
+				ms.prepend(`import "${starlightPageImportSource}";\n`);
+				return {
+					code: ms.toString(),
+					map: ms.generateMap({ hires: "boundary" })
+				};
+			}
+		}
+	};
+}
+//#endregion
+export { vitePluginStarlightCssLayerOrder };

package/dist/integrations/vite-lazy-barrel-optimization.d.ts

@@ -0,0 +1,12 @@
+import { ViteUserConfig } from "astro";
+//#region src/integrations/vite-lazy-barrel-optimization.d.ts
+/**
+ * Vite plugin that marks the Starlight components barrel file as having no side effects so that
+ * lazy barrel optimization can be applied to it.
+ *
+ * @see https://rolldown.rs/in-depth/lazy-barrel-optimization
+ */
+declare function vitePluginStarlightLazyBarrelOptimization(): VitePlugin;
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
+//#endregion
+export { vitePluginStarlightLazyBarrelOptimization };

package/dist/integrations/vite-lazy-barrel-optimization.js

@@ -0,0 +1,33 @@
+import { fileURLToPath } from "node:url";
+//#region src/integrations/vite-lazy-barrel-optimization.ts
+const componentsBarrelIdFilter = /[\\/]components\.ts(?:\?.*)?$/;
+const backSlashRegex = /\\/g;
+const queryStringRegex = /\?.*$/;
+const starlightComponentsBarrelId = normalizeId(fileURLToPath(new URL("../components.ts", import.meta.url)));
+/**
+* Vite plugin that marks the Starlight components barrel file as having no side effects so that
+* lazy barrel optimization can be applied to it.
+*
+* @see https://rolldown.rs/in-depth/lazy-barrel-optimization
+*/
+function vitePluginStarlightLazyBarrelOptimization() {
+	return {
+		name: "vite-plugin-starlight-lazy-barrel-optimization",
+		enforce: "pre",
+		transform: {
+			filter: { id: componentsBarrelIdFilter },
+			handler(code, id) {
+				if (normalizeId(id) !== starlightComponentsBarrelId) return;
+				return {
+					code,
+					moduleSideEffects: false
+				};
+			}
+		}
+	};
+}
+function normalizeId(id) {
+	return id.replace(backSlashRegex, "/").replace(queryStringRegex, "");
+}
+//#endregion
+export { vitePluginStarlightLazyBarrelOptimization };

package/dist/integrations/vite-virtual-modules.d.ts

@@ -0,0 +1,14 @@
+import { StarlightConfig } from "../utils/user-config.js";
+import { PluginTranslations } from "../utils/plugins.js";
+import { AstroConfig, HookParameters, ViteUserConfig } from "astro";
+//#region src/integrations/vite-virtual-modules.d.ts
+/** Vite plugin that exposes Starlight user config and project context via virtual modules. */
+declare function vitePluginStarlightVirtualModules({ command, isNodeCompatibleEnv }: {
+  command: HookParameters<'astro:config:setup'>['command'];
+  isNodeCompatibleEnv: boolean;
+}, opts: StarlightConfig, { build, legacy, root, srcDir, trailingSlash }: Pick<AstroConfig, 'root' | 'srcDir' | 'trailingSlash'> & {
+  build: Pick<AstroConfig['build'], 'format'>;
+  legacy: Pick<AstroConfig['legacy'], 'collectionsBackwardsCompat'>;
+}, pluginTranslations: PluginTranslations): NonNullable<ViteUserConfig['plugins']>[number];
+//#endregion
+export { vitePluginStarlightVirtualModules };

package/dist/integrations/vite-virtual-modules.js

@@ -0,0 +1,108 @@
+import { resolveCollectionPath } from "../utils/collection-fs.js";
+import { getAllNewestCommitDate } from "../utils/git.js";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+//#region src/integrations/vite-virtual-modules.ts
+const pluginResolveIdIdFilter = /^virtual:starlight\//;
+const pluginLoadIdFilter = /^\x00virtual:starlight\//;
+function resolveVirtualModuleId(id) {
+	return `\0${id}`;
+}
+/** Vite plugin that exposes Starlight user config and project context via virtual modules. */
+function vitePluginStarlightVirtualModules({ command, isNodeCompatibleEnv }, opts, { build, legacy, root, srcDir, trailingSlash }, pluginTranslations) {
+	/**
+	* Resolves module IDs to a usable format:
+	* - Relative paths (e.g. `'./module.js'`) are resolved against `base` and formatted as an absolute path.
+	* - Package identifiers (e.g. `'module'`) are returned unchanged.
+	*
+	* By default, `base` is the project root directory.
+	*/
+	const resolveId = (id, base = root) => JSON.stringify(id.startsWith(".") ? resolve(fileURLToPath(base), id) : id);
+	/**
+	* Resolves a path to a Starlight file relative to this file.
+	* When used with TypeScript files, makes sure to not include the `.ts` extension to ensure
+	* proper resolution when transpiled to JavaScript.
+	* @example
+	* resolveLocalPath('../utils/git');
+	* // => '"/users/houston/docs/node_modules/@astrojs/starlight/utils/git"'
+	* @example
+	* resolveLocalPath('../style/global.css');
+	* // => '"/users/houston/docs/node_modules/@astrojs/starlight/style/global.css"'
+	*/
+	const resolveLocalPath = (path) => JSON.stringify(fileURLToPath(new URL(path, import.meta.url)));
+	const rootPath = fileURLToPath(root);
+	const docsPath = resolveCollectionPath("docs", srcDir);
+	let collectionConfigImportPath = resolve(fileURLToPath(srcDir), "./content.config.ts");
+	if (legacy.collectionsBackwardsCompat && !existsSync(collectionConfigImportPath)) collectionConfigImportPath = resolve(fileURLToPath(srcDir), "./content/config.ts");
+	const virtualComponentModules = Object.fromEntries(Object.entries(opts.components).map(([name, path]) => [`virtual:starlight/components/${name}`, `export { default } from ${resolveId(path)};`]));
+	/** Map of virtual module names to their code contents as strings. */
+	const modules = {
+		"virtual:starlight/user-config": `export default ${JSON.stringify(opts)}`,
+		"virtual:starlight/project-context": `export default ${JSON.stringify({
+			build: { format: build.format },
+			root,
+			srcDir,
+			trailingSlash
+		})}`,
+		"virtual:starlight/git-info": (command !== "build" && isNodeCompatibleEnv ? `import { makeAPI } from ${resolveLocalPath("../utils/git")};const api = makeAPI(${JSON.stringify(rootPath)});` : `import { makeAPI } from ${resolveLocalPath("../utils/gitInlined")};const api = makeAPI(${JSON.stringify(getAllNewestCommitDate(rootPath, docsPath))});`) + "export const getNewestCommitDate = api.getNewestCommitDate;",
+		/**
+		* Module containing styles for features that can be toggled on or off such as heading anchor links.
+		*/
+		"virtual:starlight/optional-css": opts.markdown.headingLinks ? `import ${resolveLocalPath("../style/anchor-links.css")};` : "",
+		/**
+		* Module containing imports of user-specified custom CSS files.
+		*/
+		"virtual:starlight/user-css": opts.customCss.map((id) => `import ${resolveId(id)};`).join(""),
+		"virtual:starlight/user-images": opts.logo ? "src" in opts.logo ? `import src from ${resolveId(opts.logo.src)}; export const logos = { dark: src, light: src };` : `import dark from ${resolveId(opts.logo.dark)}; import light from ${resolveId(opts.logo.light)}; export const logos = { dark, light };` : "export const logos = {};",
+		"virtual:starlight/collection-config": `let userCollections;
+			try {
+				userCollections = (await import(${JSON.stringify(collectionConfigImportPath)})).collections;
+			} catch {}
+			export const collections = userCollections;`,
+		"virtual:starlight/plugin-translations": `export default ${JSON.stringify(pluginTranslations)}`,
+		/**
+		* Exports an array of route middleware functions.
+		* For example, might generate a module that looks like:
+		*
+		* ```js
+		* import { onRequest as routeMiddleware0 } from "/users/houston/docs/src/middleware";
+		* import { onRequest as routeMiddleware1 } from "@houston-inc/plugin/middleware";
+		*
+		* export const routeMiddleware = [
+		* 	routeMiddleware0,
+		* 	routeMiddleware1,
+		* ];
+		* ```
+		*/
+		"virtual:starlight/route-middleware": opts.routeMiddleware.reduce(([imports, entries], id, index) => {
+			const importName = `routeMiddleware${index}`;
+			imports += `import { onRequest as ${importName} } from ${resolveId(id)};\n`;
+			entries += `\t${importName},\n`;
+			return [imports, entries];
+		}, ["", "export const routeMiddleware = [\n"]).join("\n") + "];",
+		/** Map of modules exporting Starlight’s templating components. */
+		"virtual:starlight/pagefind-config": `export const pagefindUserConfig = ${JSON.stringify(opts.pagefind || {})}`,
+		...virtualComponentModules
+	};
+	/** Mapping names prefixed with `\0` to their original form. */
+	const resolutionMap = Object.fromEntries(Object.keys(modules).map((key) => [resolveVirtualModuleId(key), key]));
+	return {
+		name: "vite-plugin-starlight-user-config",
+		resolveId: {
+			filter: { id: pluginResolveIdIdFilter },
+			handler(id) {
+				if (id in modules) return resolveVirtualModuleId(id);
+			}
+		},
+		load: {
+			filter: { id: pluginLoadIdFilter },
+			handler(id) {
+				const resolution = resolutionMap[id];
+				if (resolution) return modules[resolution];
+			}
+		}
+	};
+}
+//#endregion
+export { vitePluginStarlightVirtualModules };

package/dist/internal.d.ts

@@ -0,0 +1,3 @@
+import { useTranslations } from "./utils/translations.js";
+import { getStarlightEcConfigPreprocessor } from "./integrations/expressive-code/preprocessor.js";
+export { getStarlightEcConfigPreprocessor, useTranslations };

package/dist/internal.js

@@ -0,0 +1,3 @@
+import { getStarlightEcConfigPreprocessor } from "./integrations/expressive-code/preprocessor.js";
+import { useTranslations } from "./utils/translations.js";
+export { getStarlightEcConfigPreprocessor, useTranslations };

package/dist/loaders.d.ts

@@ -0,0 +1,20 @@
+import { Loader, glob } from "astro/loaders";
+//#region src/loaders.d.ts
+type GlobOptions = Parameters<typeof glob>[0];
+type GenerateIdFunction = NonNullable<GlobOptions['generateId']>;
+/**
+ * Loads content files from the `src/content/docs/` directory, ignoring filenames starting with `_`.
+ */
+declare function docsLoader({ generateId }?: {
+  /**
+   * Function that generates an ID for an entry. Default implementation generates a slug from the entry path.
+   * @returns The ID of the entry. Must be unique per collection.
+   **/
+  generateId?: GenerateIdFunction;
+}): Loader;
+/**
+ * Loads data files from the `src/content/i18n/` directory, ignoring filenames starting with `_`.
+ */
+declare function i18nLoader(): Loader;
+//#endregion
+export { docsLoader, i18nLoader };

package/dist/loaders.js

@@ -0,0 +1,49 @@
+import { getCollectionPathFromRoot } from "./utils/collection.js";
+import { glob } from "astro/loaders";
+//#region src/loaders.ts
+const docsExtensions = [
+	"markdown",
+	"mdown",
+	"mkdn",
+	"mkd",
+	"mdwn",
+	"md",
+	"mdx"
+];
+const i18nExtensions = [
+	"json",
+	"yml",
+	"yaml"
+];
+/**
+* Loads content files from the `src/content/docs/` directory, ignoring filenames starting with `_`.
+*/
+function docsLoader({ generateId } = {}) {
+	return {
+		name: "starlight-docs-loader",
+		load: createGlobLoadFn("docs", generateId)
+	};
+}
+/**
+* Loads data files from the `src/content/i18n/` directory, ignoring filenames starting with `_`.
+*/
+function i18nLoader() {
+	return {
+		name: "starlight-i18n-loader",
+		load: createGlobLoadFn("i18n")
+	};
+}
+function createGlobLoadFn(collection, generateId) {
+	return (context) => {
+		const extensions = collection === "docs" ? docsExtensions : i18nExtensions;
+		if (collection === "docs" && context.config.integrations.find(({ name }) => name === "@astrojs/markdoc")) extensions.push("mdoc");
+		const options = {
+			base: getCollectionPathFromRoot(collection, context.config),
+			pattern: `**/[^_]*.{${extensions.join(",")}}`
+		};
+		if (generateId) options.generateId = generateId;
+		return glob(options).load(context);
+	};
+}
+//#endregion
+export { docsLoader, i18nLoader };

package/dist/locals.d.ts

@@ -0,0 +1,15 @@
+import { APIContext } from "astro";
+//#region src/locals.d.ts
+declare const onRequest: any;
+/**
+ * Sets up a `starlightRoute` property on locals. Initially, this will throw an error if accessed.
+ * When rendering, Starlight’s routes set `starlightRoute` with the resolved route data object for
+ * the current page.
+ *
+ * This ensures Starlight components can easily access `starlightRoute` without needing type guards,
+ * we can throw a helpful message if `starlightRoute` is accessed on non-Starlight pages, and we
+ * avoid generating route data in this middleware which also runs for non-Starlight route.
+ */
+declare function initializeStarlightRoute(context: APIContext): void;
+//#endregion
+export { initializeStarlightRoute, onRequest };

package/dist/locals.js

@@ -0,0 +1,33 @@
+import { useTranslations } from "./utils/translations.js";
+import { AstroError } from "astro/errors";
+import { defineMiddleware } from "astro:middleware";
+//#region src/locals.ts
+const onRequest = defineMiddleware(async (context, next) => {
+	context.locals.t = useTranslations(context.currentLocale);
+	initializeStarlightRoute(context);
+	return next();
+});
+/**
+* Sets up a `starlightRoute` property on locals. Initially, this will throw an error if accessed.
+* When rendering, Starlight’s routes set `starlightRoute` with the resolved route data object for
+* the current page.
+*
+* This ensures Starlight components can easily access `starlightRoute` without needing type guards,
+* we can throw a helpful message if `starlightRoute` is accessed on non-Starlight pages, and we
+* avoid generating route data in this middleware which also runs for non-Starlight route.
+*/
+function initializeStarlightRoute(context) {
+	if ("starlightRoute" in context.locals) return;
+	const state = { routeData: void 0 };
+	Object.defineProperty(context.locals, "starlightRoute", {
+		get() {
+			if (!state.routeData) throw new AstroError("`locals.starlightRoute` is not defined", "This usually means a component that accesses `locals.starlightRoute` is being rendered outside of a Starlight page, which is not supported.\n\nIf this is a component you authored, you can do one of the following:\n\n1. Avoid using this component in non-Starlight pages.\n2. Wrap the code that reads `locals.starlightRoute` in a  `try/catch` block and handle the cases where `starlightRoute` is not available.\n\nIf this is a Starlight built-in or third-party component, you may need to report a bug or avoid this use of the component.");
+			return state.routeData;
+		},
+		set(routeData) {
+			state.routeData = routeData;
+		}
+	});
+}
+//#endregion
+export { initializeStarlightRoute, onRequest };

package/dist/package.js

@@ -0,0 +1,4 @@
+//#region package.json
+var version = "0.42.0";
+//#endregion
+export { version };

package/{props.ts → dist/props.d.ts}

@@ -1,6 +1,6 @@
-import type { StarlightRouteData } from './utils/routing/types';
-export type { StarlightPageProps } from './utils/starlight-page';
-
+import { StarlightRouteData } from "./utils/routing/types.js";
+import { StarlightPageProps } from "./utils/starlight-page.js";
+//#region src/props.d.ts
 /**
  * @deprecated The `Props` type is deprecated. If updating an override to use
  * `Astro.locals.starlightRoute` instead of `Astro.props`, import the new `StarlightRouteData`
@@ -11,4 +11,6 @@ export type { StarlightPageProps } from './utils/starlight-page';
  * ---
  * ```
  */
-export type Props = StarlightRouteData;
+type Props = StarlightRouteData;
+//#endregion
+export { Props, type StarlightPageProps };

package/dist/props.js

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

package/dist/route-data.d.ts

@@ -0,0 +1,7 @@
+import { StarlightRouteData } from "./utils/routing/types.js";
+import { APIContext } from "astro";
+//#region src/route-data.d.ts
+type RouteMiddlewareHandler = (context: APIContext, next: () => Promise<void>) => void | Promise<void>;
+declare function defineRouteMiddleware(fn: RouteMiddlewareHandler): RouteMiddlewareHandler;
+//#endregion
+export { RouteMiddlewareHandler, type StarlightRouteData, defineRouteMiddleware };

package/dist/route-data.js

@@ -0,0 +1,6 @@
+//#region src/route-data.ts
+function defineRouteMiddleware(fn) {
+	return fn;
+}
+//#endregion
+export { defineRouteMiddleware };