@astrojs/starlight 0.41.10 → 0.42.0

package/components-internals/TableOfContents/starlight-toc.ts

@@ -1,127 +0,0 @@
-import { PAGE_TITLE_ID } from '../../constants';
-
-export class StarlightTOC extends HTMLElement {
-	private _current = this.querySelector<HTMLAnchorElement>('a[aria-current="true"]');
-	private minH = parseInt(this.dataset.minH || '2', 10);
-	private maxH = parseInt(this.dataset.maxH || '3', 10);
-
-	/**
-	 * CSS selector string that matches only headings that can appear in the table of contents.
-	 * Generates a selector like `h1#_top,:where(h2,h3)[id]`.
-	 */
-	private tocHeadingSelector =
-		`h1#${PAGE_TITLE_ID},` +
-		`:where(${[...Array.from({ length: 1 + this.maxH - this.minH }).map((_, index) => `h${this.minH + index}`)].join()})[id]`;
-
-	protected set current(link: HTMLAnchorElement) {
-		if (link === this._current) return;
-		if (this._current) this._current.removeAttribute('aria-current');
-		link.setAttribute('aria-current', 'true');
-		this._current = link;
-	}
-
-	private onIdle = (cb: IdleRequestCallback) =>
-		(window.requestIdleCallback || ((cb) => setTimeout(cb, 1)))(cb);
-
-	constructor() {
-		super();
-		this.onIdle(() => this.init());
-	}
-
-	private init = (): void => {
-		/** All the links in the table of contents. */
-		const links = [...this.querySelectorAll('a')];
-
-		/** Test if an element is a table-of-contents heading. */
-		const isHeading = (el: Element): el is HTMLHeadingElement =>
-			el.matches(this.tocHeadingSelector);
-
-		/** Walk up the DOM to find the nearest heading. */
-		const getElementHeading = (el: Element | null): HTMLHeadingElement | null => {
-			if (!el) return null;
-			const origin = el;
-			while (el) {
-				// Short circuit if we reach the top-level content container or one of the other containers in main.
-				if (el.matches('.sl-markdown-content, main > *')) {
-					return document.getElementById(PAGE_TITLE_ID) as HTMLHeadingElement;
-				}
-				if (isHeading(el)) return el;
-				// Find the first heading that is a child of this element, and return it if there is one.
-				const childHeading = el.querySelector<HTMLHeadingElement>(this.tocHeadingSelector);
-				if (childHeading) return childHeading;
-				// Assign the previous sibling’s last, most deeply nested child to el.
-				el = el.previousElementSibling;
-				while (el?.lastElementChild) {
-					el = el.lastElementChild;
-				}
-				// Look for headings amongst siblings.
-				const h = getElementHeading(el);
-				if (h) return h;
-			}
-			// Walk back up the parent.
-			return getElementHeading(origin.parentElement);
-		};
-
-		/** Handle intersections and set the current link to the heading for the current intersection. */
-		const setCurrent: IntersectionObserverCallback = (entries) => {
-			for (const { isIntersecting, target } of entries) {
-				if (!isIntersecting) continue;
-				const heading = getElementHeading(target);
-				if (!heading) continue;
-				const link = links.find((link) => link.hash === '#' + encodeURIComponent(heading.id));
-				if (link) {
-					this.current = link;
-					break;
-				}
-			}
-		};
-
-		// Observe the following elements:
-		// - headings that appear in the table of contents
-		// - siblings of those headings or of the `.sl-heading-wrapper` added by Starlight’s anchor links feature
-		// - direct children of `.sl-markdown-content` to include elements before the first subheading
-		// - direct children of `main` that don’t include headings (mainly to target Starlight’s banner)
-		// Ignore any elements that themselves contain a table-of-contents heading, as we are already observing those children.
-		const toObserve = document.querySelectorAll(
-			[
-				`main :where(${this.tocHeadingSelector})`,
-				`main :where(${this.tocHeadingSelector}, .sl-heading-wrapper) ~ *:not(:has(${this.tocHeadingSelector}))`,
-				`main .sl-markdown-content > *:not(:has(${this.tocHeadingSelector}))`,
-				`main > *:not(:has(${this.tocHeadingSelector}))`,
-			].join()
-		);
-
-		let observer: IntersectionObserver | undefined;
-		const observe = () => {
-			if (observer) return;
-			observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() });
-			toObserve.forEach((h) => observer!.observe(h));
-		};
-		observe();
-
-		let timeout: NodeJS.Timeout;
-		window.addEventListener('resize', () => {
-			// Disable intersection observer while window is resizing.
-			if (observer) {
-				observer.disconnect();
-				observer = undefined;
-			}
-			clearTimeout(timeout);
-			timeout = setTimeout(() => this.onIdle(observe), 200);
-		});
-	};
-
-	private getRootMargin(): `-${number}px 0% ${number}px` {
-		const navBarHeight = document.querySelector('header')?.getBoundingClientRect().height || 0;
-		// `<summary>` only exists in mobile ToC, so will fall back to 0 in large viewport component.
-		const mobileTocHeight = this.querySelector('summary')?.getBoundingClientRect().height || 0;
-		/** Start intersections at nav height + 2rem padding. */
-		const top = navBarHeight + mobileTocHeight + 32;
-		/** End intersections `53px` later. This is slightly more than the maximum `margin-top` in Markdown content. */
-		const bottom = top + 53;
-		const height = document.documentElement.clientHeight;
-		return `-${top}px 0% ${bottom - height}px`;
-	}
-}
-
-customElements.define('starlight-toc', StarlightTOC);

package/constants.ts

@@ -1,4 +0,0 @@
-// N.B. THIS FILE IS IMPORTED IN BOTH SERVER- AND CLIENT-SIDE CODE.
-// THINK TWICE BEFORE ADDING STUFF AS IT WILL GET SHIPPED TO THE CLIENT.
-
-export const PAGE_TITLE_ID = '_top';

package/expressive-code.mjs

@@ -1,23 +0,0 @@
-/**
- * @file This file is exported by Starlight as `@astrojs/starlight/expressive-code`.
- *
- * It is required by the `<Code>` component to access the same configuration preprocessor
- * function as the one used by the integration.
- *
- * It also provides access to all of the Expressive Code classes and functions without having
- * to install `astro-expressive-code` as an additional dependency into a user's project
- * (and thereby risiking version conflicts).
- *
- * Note: This file is intentionally not a TypeScript module to allow access to all exported
- * functionality even if TypeScript is not available, e.g. from the `ec.config.mjs` file
- * that does not get processed by Vite.
- */
-
-export * from 'astro-expressive-code';
-
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-// @ts-ignore - Types are provided by the separate `expressive-code.d.ts` file and this may not be
-// a type error for some users running `tsc --noEmit` depending on their `tsconfig.json` settings.
-export function defineEcConfig(config) {
-	return config;
-}

package/global.d.ts

@@ -1,11 +0,0 @@
-interface StarlightThemeProvider {
-	updatePickers(theme?: string): void;
-}
-
-export declare global {
-	var StarlightThemeProvider: StarlightThemeProvider;
-
-	interface Window {
-		StarlightThemeProvider: StarlightThemeProvider;
-	}
-}

package/i18n.d.ts

@@ -1,18 +0,0 @@
-/*
- * This file imports the original `i18next` types and extends them to configure the
- * Starlight namespace.
- *
- * Note that the top-level `import` makes this module non-ambient, so can’t be
- * combined with other `.d.ts` files such as `locals.d.ts`.
- */
-
-import 'i18next';
-
-declare module 'i18next' {
-	interface CustomTypeOptions {
-		defaultNS: typeof import('./utils/createTranslationSystem').I18nextNamespace;
-		resources: {
-			starlight: Record<import('./utils/createTranslationSystem').I18nKeys, string>;
-		};
-	}
-}

package/index.ts

@@ -1,200 +0,0 @@
-/**
- * These triple-slash directives defines dependencies to various declaration files that will be
- * loaded when a user imports the Starlight integration in their Astro configuration file. These
- * directives must be first at the top of the file and can only be preceded by this comment.
- */
-/// <reference path="./locals.d.ts" />
-/// <reference path="./i18n.d.ts" />
-/// <reference path="./virtual.d.ts" />
-
-import mdx from '@astrojs/mdx';
-import type { AstroIntegration } from 'astro';
-import { AstroError } from 'astro/errors';
-import type { MarkdownProcessorPluginOptions } from './integrations/markdown-processor';
-import {
-	applyStarlightMarkdownPlugins,
-	starlightDirectivesRestorationIntegration,
-	unifiedIntegration,
-} from './integrations/markdown-plugins';
-import { starlightExpressiveCode } from './integrations/expressive-code/index';
-import { starlightPagefind } from './integrations/pagefind';
-import { starlightSitemap } from './integrations/sitemap';
-import { vitePluginStarlightCssLayerOrder } from './integrations/vite-layer-order';
-import { vitePluginStarlightLazyBarrelOptimization } from './integrations/vite-lazy-barrel-optimization';
-import { vitePluginStarlightVirtualModules } from './integrations/vite-virtual-modules';
-import {
-	injectPluginTranslationsTypes,
-	runPlugins,
-	type PluginTranslations,
-	type StarlightUserConfigWithPlugins,
-} from './utils/plugins';
-import { processI18nConfig } from './utils/i18n';
-import type { StarlightConfig } from './types';
-
-export default function StarlightIntegration(
-	userOpts: StarlightUserConfigWithPlugins
-): AstroIntegration {
-	if (typeof userOpts !== 'object' || userOpts === null || Array.isArray(userOpts))
-		throw new AstroError(
-			'Invalid config passed to starlight integration',
-			`The Starlight integration expects a configuration object with at least a \`title\` property.\n\n` +
-				`See more details in the [Starlight configuration reference](https://starlight.astro.build/reference/configuration/)\n`
-		);
-	const { plugins, ...opts } = userOpts;
-	let userConfig: StarlightConfig;
-	let pluginTranslations: PluginTranslations = {};
-	return {
-		name: '@astrojs/starlight',
-		hooks: {
-			'astro:config:setup': async ({
-				addMiddleware,
-				command,
-				config,
-				injectRoute,
-				isRestart,
-				logger,
-				updateConfig,
-			}) => {
-				// Run plugins to get the updated configuration and any extra Astro integrations to load.
-				const pluginResult = await runPlugins(opts, plugins, {
-					command,
-					config,
-					isRestart,
-					logger,
-				});
-				// Process the Astro and Starlight configurations for i18n and translations.
-				const { astroI18nConfig, starlightConfig } = processI18nConfig(
-					pluginResult.starlightConfig,
-					config.i18n
-				);
-
-				const { integrations, useTranslations, absolutePathToLang } = pluginResult;
-				pluginTranslations = pluginResult.pluginTranslations;
-				userConfig = starlightConfig;
-
-				addMiddleware({ entrypoint: '@astrojs/starlight/locals', order: 'pre' });
-
-				if (!starlightConfig.disable404Route) {
-					injectRoute({
-						pattern: '404',
-						entrypoint: starlightConfig.prerender
-							? '@astrojs/starlight/routes/static/404.astro'
-							: '@astrojs/starlight/routes/ssr/404.astro',
-						prerender: starlightConfig.prerender,
-					});
-				}
-				injectRoute({
-					pattern: '[...slug]',
-					entrypoint: starlightConfig.prerender
-						? '@astrojs/starlight/routes/static/index.astro'
-						: '@astrojs/starlight/routes/ssr/index.astro',
-					prerender: starlightConfig.prerender,
-				});
-
-				// Resolve the configured processor and the optional Unified integration up front before
-				// wiring up the integrations below.
-				const processor = config.markdown.processor;
-				const unified = await unifiedIntegration;
-
-				// Add built-in integrations only if they are not already added by the user through the
-				// config or by a plugin.
-				const allIntegrations = [...config.integrations, ...integrations];
-				if (!allIntegrations.find(({ name }) => name === 'astro-expressive-code')) {
-					integrations.push(
-						...starlightExpressiveCode({ astroConfig: config, starlightConfig, useTranslations })
-					);
-				}
-				if (!allIntegrations.find(({ name }) => name === '@astrojs/sitemap')) {
-					integrations.push(starlightSitemap(starlightConfig));
-				}
-				if (!allIntegrations.find(({ name }) => name === '@astrojs/mdx')) {
-					integrations.push(mdx({ optimize: true }));
-				}
-
-				const markdownProcessorOptions: MarkdownProcessorPluginOptions = {
-					starlightConfig,
-					astroConfig: config,
-					useTranslations,
-					absolutePathToLang,
-				};
-
-				// We push our plugins onto the processor's options.
-				applyStarlightMarkdownPlugins(processor, markdownProcessorOptions, unified, logger);
-
-				// Add Starlight directives restoration integration at the end of the list so that
-				// remark/mdast plugins injected by Starlight plugins through Astro integrations can
-				// handle text and leaf directives before they are transformed back to their original
-				// form.
-				integrations.push(starlightDirectivesRestorationIntegration());
-
-				// Add integrations immediately after Starlight in the config array.
-				// e.g. if a user has `integrations: [starlight(), tailwind()]`, then the order will be
-				// `[starlight(), expressiveCode(), sitemap(), mdx(), tailwind()]`.
-				// This ensures users can add integrations before/after Starlight and we respect that order.
-				const selfIndex = config.integrations.findIndex((i) => i.name === '@astrojs/starlight');
-				config.integrations.splice(selfIndex + 1, 0, ...integrations);
-
-				// TODO: refactor once there is a reliable way to detect non-Node.js compatible
-				// environments, rather than relying on the presence of specific adapters/integrations.
-				const isCloudflareEnv =
-					config.adapter?.name === '@astrojs/cloudflare' ||
-					config.integrations.some(({ name }) => name === '@astrojs/cloudflare');
-				const isNodeCompatibleEnv = !isCloudflareEnv;
-
-				updateConfig({
-					vite: {
-						plugins: [
-							vitePluginStarlightCssLayerOrder(),
-							vitePluginStarlightLazyBarrelOptimization(),
-							vitePluginStarlightVirtualModules(
-								{ command, isNodeCompatibleEnv },
-								starlightConfig,
-								config,
-								pluginTranslations
-							),
-						],
-						ssr: isNodeCompatibleEnv
-							? {}
-							: {
-									optimizeDeps: {
-										include: [
-											// Prebundle some dependencies for non-Node.js compatible environments to
-											// speed up dev server start time and prevent restarts.
-											'@astrojs/cloudflare/entrypoints/server',
-											'@astrojs/starlight>i18next',
-											'@astrojs/starlight>js-yaml',
-											'@astrojs/starlight>klona/lite',
-											// TODO: once Expressive Code is refactored/fixed, remove this workaround for
-											// Expressive Code relying on CJS dependencies like postcss not compatible
-											// with non-Node.js compatible environments like Cloudflare.
-											'@astrojs/starlight>astro-expressive-code/components',
-											'@astrojs/starlight>astro-expressive-code>hast-util-select',
-											'@astrojs/starlight>astro-expressive-code>rehype',
-											'@astrojs/starlight>astro-expressive-code>unist-util-visit',
-											'@astrojs/starlight>astro-expressive-code>rehype-format',
-											'@astrojs/starlight>astro-expressive-code>hastscript',
-											'@astrojs/starlight>astro-expressive-code>hast-util-from-html',
-											'@astrojs/starlight>astro-expressive-code>hast-util-to-string',
-											'@astrojs/starlight>astro-expressive-code>@expressive-code/core>postcss',
-										],
-									},
-								},
-					},
-					scopedStyleStrategy: 'where',
-					// If not already configured, default to prefetching all links on hover.
-					prefetch: config.prefetch ?? { prefetchAll: true },
-					i18n: astroI18nConfig,
-				});
-			},
-
-			'astro:config:done': ({ injectTypes }) => {
-				injectPluginTranslationsTypes(pluginTranslations, injectTypes);
-			},
-
-			'astro:build:done': async (options) => {
-				if (!userConfig.pagefind) return;
-				return starlightPagefind(options);
-			},
-		},
-	};
-}

package/integrations/aside-utils.ts

@@ -1,41 +0,0 @@
-import { AstroError } from 'astro/errors';
-import { Icons, type StarlightIcon } from '../components-internals/Icons';
-
-export const asideVariants = ['note', 'tip', 'caution', 'danger'] as const;
-export type AsideVariant = (typeof asideVariants)[number];
-
-// A map of aside variants to their default Starlight icon names.
-const asideIconNames: Record<AsideVariant, StarlightIcon> = {
-	note: 'information',
-	tip: 'rocket',
-	caution: 'warning',
-	danger: 'error',
-};
-
-const asideVariantSet = new Set<string>(asideVariants);
-export function isAsideVariant(value: string): value is AsideVariant {
-	return asideVariantSet.has(value);
-}
-
-export function getAsideIconName(variant: AsideVariant, customIcon?: string | null): StarlightIcon {
-	let iconName = asideIconNames[variant];
-
-	if (customIcon) {
-		iconName = customIcon as StarlightIcon;
-		if (!Icons[iconName]) throwInvalidAsideIconError(iconName);
-	}
-
-	return iconName;
-}
-
-export function getAsideIcon(variant: AsideVariant, customIcon?: string | null) {
-	return Icons[getAsideIconName(variant, customIcon)];
-}
-
-function throwInvalidAsideIconError(icon: string) {
-	throw new AstroError(
-		'Invalid aside icon',
-		`An aside custom icon must be set to the name of one of Starlight’s built-in icons, but received \`${icon}\`.\n\n` +
-			'See https://starlight.astro.build/reference/icons/#all-icons for a list of available icons.'
-	);
-}

package/integrations/expressive-code/hast.d.ts

@@ -1,5 +0,0 @@
-/**
- * @file This file provides the types for Starlight's `@astrojs/starlight/expressive-code/hast` export.
- */
-
-export * from 'astro-expressive-code/hast';

package/integrations/expressive-code/hast.mjs

@@ -1,9 +0,0 @@
-/**
- * @file This file is exported by Starlight as `@astrojs/starlight/expressive-code/hast`.
- *
- * Note: This file is intentionally not a TypeScript module to allow access to all exported
- * functionality even if TypeScript is not available, e.g. from the `ec.config.mjs` file
- * that does not get processed by Vite.
- */
-
-export * from 'astro-expressive-code/hast';

package/integrations/expressive-code/index.ts

@@ -1,125 +0,0 @@
-import { astroExpressiveCode, type AstroExpressiveCodeOptions } from 'astro-expressive-code';
-import type { AstroConfig, AstroIntegration } from 'astro';
-import type { HookParameters, StarlightConfig } from '../../types';
-import { getStarlightEcConfigPreprocessor } from './preprocessor';
-import { type ThemeObjectOrBundledThemeName } from './theming';
-import { getCollectionPosixPath } from '../../utils/collection-fs';
-
-export type StarlightExpressiveCodeOptions = Omit<AstroExpressiveCodeOptions, 'themes'> & {
-	/**
-	 * Set the themes used to style code blocks.
-	 *
-	 * See the [Expressive Code `themes` documentation](https://expressive-code.com/guides/themes/)
-	 * for details of the supported theme formats.
-	 *
-	 * Starlight uses the dark and light variants of Sarah Drasner’s
-	 * [Night Owl theme](https://github.com/sdras/night-owl-vscode-theme) by default.
-	 *
-	 * If you provide at least one dark and one light theme, Starlight will automatically keep
-	 * the active code block theme in sync with the current site theme. Configure this behavior
-	 * with the [`useStarlightDarkModeSwitch`](#usestarlightdarkmodeswitch) option.
-	 *
-	 * Defaults to `['starlight-dark', 'starlight-light']`.
-	 */
-	themes?: ThemeObjectOrBundledThemeName[] | undefined;
-	/**
-	 * When `true`, code blocks automatically switch between light and dark themes when the
-	 * site theme changes.
-	 *
-	 * When `false`, you must manually add CSS to handle switching between multiple themes.
-	 *
-	 * **Note**: When setting `themes`, you must provide at least one dark and one light theme
-	 * for the Starlight dark mode switch to work.
-	 *
-	 * Defaults to `true`.
-	 */
-	useStarlightDarkModeSwitch?: boolean | undefined;
-	/**
-	 * When `true`, Starlight's CSS variables are used for the colors of code block UI elements
-	 * (backgrounds, buttons, shadows etc.), matching the
-	 * [site color theme](/guides/css-and-tailwind/#theming).
-	 *
-	 * When `false`, the colors provided by the active syntax highlighting theme are used for
-	 * these elements.
-	 *
-	 * Defaults to `true` if the `themes` option is not set (= you are using Starlight's
-	 * default themes), and `false` otherwise.
-	 *
-	 * **Note**: When manually setting this to `true` with your custom set of `themes`, you must
-	 * provide at least one dark and one light theme to ensure proper color contrast.
-	 */
-	useStarlightUiThemeColors?: boolean | undefined;
-};
-
-type StarlightEcIntegrationOptions = {
-	astroConfig: AstroConfig;
-	starlightConfig: StarlightConfig;
-	useTranslations: HookParameters<'config:setup'>['useTranslations'];
-};
-
-export const starlightExpressiveCode = ({
-	astroConfig,
-	starlightConfig,
-	useTranslations,
-}: StarlightEcIntegrationOptions): AstroIntegration[] => {
-	// If Expressive Code is disabled, add a shim to prevent build errors and provide
-	// a helpful error message in case the user tries to use the `<Code>` component
-	if (starlightConfig.expressiveCode === false) {
-		const modules: Record<string, string> = {
-			'virtual:astro-expressive-code/api': 'export default {}',
-			'virtual:astro-expressive-code/config': 'export default {}',
-			'virtual:astro-expressive-code/preprocess-config': `throw new Error("Starlight's
-				Code component requires Expressive Code, which is disabled in your Starlight config.
-				Please remove \`expressiveCode: false\` from your config or import Astro's built-in
-				Code component from 'astro:components' instead.")`.replace(/\s+/g, ' '),
-		};
-
-		return [
-			{
-				name: 'astro-expressive-code-shim',
-				hooks: {
-					'astro:config:setup': ({ updateConfig }) => {
-						updateConfig({
-							vite: {
-								plugins: [
-									{
-										name: 'vite-plugin-astro-expressive-code-shim',
-										enforce: 'post',
-										resolveId: (id) => (id in modules ? `\0${id}` : undefined),
-										load: (id) => (id?.[0] === '\0' ? modules[id.slice(1)] : undefined),
-									},
-								],
-							},
-						});
-					},
-				},
-			},
-		];
-	}
-
-	const configArgs =
-		typeof starlightConfig.expressiveCode === 'object'
-			? (starlightConfig.expressiveCode as AstroExpressiveCodeOptions)
-			: {};
-
-	const docsPath = getCollectionPosixPath('docs', astroConfig.srcDir);
-
-	return [
-		astroExpressiveCode({
-			...configArgs,
-			customConfigPreprocessors: {
-				preprocessAstroIntegrationConfig: getStarlightEcConfigPreprocessor({
-					docsPath,
-					starlightConfig,
-					useTranslations,
-				}),
-				preprocessComponentConfig: `
-					import starlightConfig from 'virtual:starlight/user-config'
-					import { useTranslations, getStarlightEcConfigPreprocessor } from '@astrojs/starlight/internal'
-
-					export default getStarlightEcConfigPreprocessor({ docsPath: ${JSON.stringify(docsPath)}, starlightConfig, useTranslations })
-				`,
-			},
-		}),
-	];
-};