@astrojs/starlight 0.41.11 → 0.42.0

package/utils/head.ts

@@ -1,235 +0,0 @@
-import config from 'virtual:starlight/user-config';
-import project from 'virtual:starlight/project-context';
-import { version } from '../package.json';
-import { type HeadConfig, HeadConfigSchema, type HeadUserConfig } from '../schemas/head';
-import type { PageProps, RouteDataContext } from './routing/data';
-import { fileWithBase } from './base';
-import { formatCanonical } from './canonical';
-import { localizedUrl } from './localizedUrl';
-import { isAbsoluteUrl } from './url';
-
-const HeadSchema = HeadConfigSchema({ source: 'content' });
-
-/** Get the head for the current page. */
-export function getHead(
-	{ entry, lang }: PageProps,
-	context: RouteDataContext,
-	siteTitle: string
-): HeadConfig {
-	const { data } = entry;
-
-	const canonical = context.site ? new URL(context.url.pathname, context.site) : undefined;
-	const canonicalHref = canonical?.href
-		? formatCanonical(canonical.href, {
-				format: project.build.format,
-				trailingSlash: project.trailingSlash,
-			})
-		: undefined;
-	const description = data.description || config.description;
-
-	const headDefaults: HeadUserConfig = [
-		{ 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 !== undefined
-			? ([{ tag: 'link', attrs: { rel: 'canonical', href: canonicalHref } }] as const)
-			: []),
-		{ tag: 'meta', attrs: { name: 'generator', content: context.generator } },
-		{
-			tag: 'meta',
-			attrs: { name: 'generator', content: `Starlight v${version}` },
-		},
-		// Favicon
-		{
-			tag: 'link',
-			attrs: {
-				rel: 'shortcut icon',
-				href: isAbsoluteUrl(config.favicon.href)
-					? config.favicon.href
-					: fileWithBase(config.favicon.href),
-				type: config.favicon.type,
-			},
-		},
-		// OpenGraph Tags
-		{ tag: 'meta', attrs: { property: 'og:title', content: data.title } },
-		{ tag: 'meta', attrs: { property: 'og:type', content: 'article' } },
-		...(canonicalHref !== undefined
-			? ([{ tag: 'meta', attrs: { property: 'og:url', content: canonicalHref } }] as const)
-			: []),
-		{ tag: 'meta', attrs: { property: 'og:locale', content: lang } },
-		...(description !== undefined
-			? ([{ tag: 'meta', attrs: { property: 'og:description', content: description } }] as const)
-			: []),
-		{ tag: 'meta', attrs: { property: 'og:site_name', content: siteTitle } },
-		// Twitter Tags
-		{
-			tag: 'meta',
-			attrs: { name: 'twitter:card', content: 'summary_large_image' },
-		},
-	];
-
-	if (description)
-		headDefaults.push({
-			tag: 'meta',
-			attrs: { name: 'description', content: description },
-		});
-
-	// Link to language alternates.
-	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,
-			},
-		});
-	}
-
-	// Link to sitemap, but only when `site` is set.
-	if (context.site) {
-		headDefaults.push({
-			tag: 'link',
-			attrs: {
-				rel: 'sitemap',
-				href: fileWithBase('/sitemap-index.xml'),
-			},
-		});
-	}
-
-	// Link to Twitter account if set in Starlight config.
-	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: HeadUserConfig, ...heads: HeadConfig[]) {
-	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: HeadConfig, entry: HeadConfig[number]): boolean {
-	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: HeadConfig, entry: HeadConfig[number], keys: string[]): boolean {
-	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: string[],
-	entry: HeadConfig[number]
-): [key: string, value: string | boolean] | undefined {
-	let attr: [string, string | boolean] | undefined;
-	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: HeadConfig, newHead: HeadConfig) {
-	return [...oldHead.filter((tag) => !hasTag(newHead, tag)), ...newHead];
-}
-
-/** Sort head tags to place important tags first and relegate “SEO” meta tags. */
-function sortHead(head: HeadConfig) {
-	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: HeadConfig[number]) {
-	// 1. Important meta tags.
-	if (
-		entry.tag === 'meta' &&
-		entry.attrs &&
-		('charset' in entry.attrs || 'http-equiv' in entry.attrs || entry.attrs.name === 'viewport')
-	) {
-		return 100;
-	}
-	// 2. Page title
-	if (entry.tag === 'title') return 90;
-	// 3. Anything that isn’t an SEO meta tag.
-	if (entry.tag !== 'meta') {
-		// The default favicon should be below any extra icons that the user may have set
-		// because if several icons are equally appropriate, the last one is used and we
-		// want to use the SVG icon when supported.
-		if (
-			entry.tag === 'link' &&
-			entry.attrs &&
-			'rel' in entry.attrs &&
-			entry.attrs.rel === 'shortcut icon'
-		) {
-			return 70;
-		}
-		return 80;
-	}
-	// 4. SEO meta tags.
-	return 0;
-}

package/utils/i18n.ts

@@ -1,221 +0,0 @@
-import type { AstroConfig } from 'astro';
-import { AstroError } from 'astro/errors';
-import type { StarlightConfig } from './user-config';
-
-/**
- * A list of well-known right-to-left languages used as a fallback when determining the text
- * direction of a locale is not supported by the `Intl.Locale` API in the current environment.
- *
- * @see getLocaleDir()
- * @see https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags
- */
-const wellKnownRTL = ['ar', 'fa', 'he', 'prs', 'ps', 'syc', 'ug', 'ur'];
-
-/** Information about the built-in default locale used as a fallback when no locales are defined. */
-export const BuiltInDefaultLocale = { ...getLocaleInfo('en'), lang: 'en' };
-
-/**
- * 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.
- */
-export function processI18nConfig(
-	starlightConfig: StarlightConfig,
-	astroI18nConfig: AstroConfig['i18n']
-) {
-	// We don't know what to do if both an Astro and Starlight i18n configuration are provided.
-	if (astroI18nConfig && !starlightConfig.isUsingBuiltInDefaultLocale) {
-		throw new AstroError(
-			'Cannot provide both an Astro `i18n` configuration and a Starlight `locales` configuration.',
-			'Remove one of the two configurations.\nSee more at https://starlight.astro.build/guides/i18n/'
-		);
-	} else if (astroI18nConfig) {
-		// If a Starlight compatible Astro i18n configuration is provided, we generate the matching
-		// Starlight configuration.
-		return {
-			astroI18nConfig,
-			starlightConfig: {
-				...starlightConfig,
-				...getStarlightI18nConfig(astroI18nConfig),
-			} as StarlightConfig,
-		};
-	}
-	// Otherwise, we generate the Astro i18n configuration based on the Starlight configuration.
-	return { astroI18nConfig: getAstroI18nConfig(starlightConfig), starlightConfig: starlightConfig };
-}
-
-/** Generate an Astro i18n configuration based on a Starlight configuration. */
-function getAstroI18nConfig(config: StarlightConfig): NonNullable<AstroConfig['i18n']> {
-	return {
-		// When using custom locale `path`s, the default locale must match one of these paths.
-		// In Starlight, this matches the `locale` property if defined, and we fallback to the `lang`
-		// property if not (which would be set to the language’s directory name by default).
-		defaultLocale:
-			// If the default locale is explicitly set to `root`, we use the `lang` property instead.
-			(config.defaultLocale.locale === 'root'
-				? config.defaultLocale.lang
-				: (config.defaultLocale.locale ?? config.defaultLocale.lang)) ?? BuiltInDefaultLocale.lang,
-		locales: config.locales
-			? Object.entries(config.locales).map(([locale, localeConfig]) => {
-					return {
-						codes: [localeConfig?.lang ?? locale],
-						path: locale === 'root' ? (localeConfig?.lang ?? BuiltInDefaultLocale.lang) : locale,
-					};
-				})
-			: [config.defaultLocale.lang],
-		routing: {
-			prefixDefaultLocale:
-				// Sites with multiple languages without a root locale.
-				(config.isMultilingual && config.locales?.root === undefined) ||
-				// Sites with a single non-root language different from the built-in default locale.
-				(!config.isMultilingual && config.locales !== undefined),
-			redirectToDefaultLocale: false,
-			fallbackType: 'redirect',
-		},
-	};
-}
-
-/** Generate a Starlight i18n configuration based on an Astro configuration. */
-function getStarlightI18nConfig(
-	astroI18nConfig: NonNullable<AstroConfig['i18n']>
-): Pick<StarlightConfig, 'isMultilingual' | 'locales' | 'defaultLocale'> {
-	if (astroI18nConfig.routing === 'manual') {
-		throw new AstroError(
-			'Starlight is not compatible with the `manual` routing option in the Astro i18n configuration.'
-		);
-	}
-
-	const prefixDefaultLocale = astroI18nConfig.routing.prefixDefaultLocale;
-	const isMultilingual = astroI18nConfig.locales.length > 1;
-	const isMonolingualWithRootLocale = !isMultilingual && !prefixDefaultLocale;
-
-	const locales = isMonolingualWithRootLocale
-		? undefined
-		: Object.fromEntries(
-				astroI18nConfig.locales.map((locale) => [
-					isDefaultAstroLocale(astroI18nConfig, locale) && !prefixDefaultLocale
-						? 'root'
-						: isAstroLocaleExtendedConfig(locale)
-							? locale.path
-							: locale,
-					inferStarlightLocaleFromAstroLocale(locale),
-				])
-			);
-
-	const defaultAstroLocale = astroI18nConfig.locales.find((locale) =>
-		isDefaultAstroLocale(astroI18nConfig, locale)
-	);
-
-	// This should never happen as Astro validation should prevent this case.
-	if (!defaultAstroLocale) {
-		throw new AstroError(
-			'Astro default locale not found.',
-			'This should never happen. Please open a new issue: https://github.com/withastro/starlight/issues/new?template=---01-bug-report.yml'
-		);
-	}
-
-	return {
-		isMultilingual,
-		locales,
-		defaultLocale: {
-			...inferStarlightLocaleFromAstroLocale(defaultAstroLocale),
-			locale:
-				isMonolingualWithRootLocale || (isMultilingual && !prefixDefaultLocale)
-					? undefined
-					: isAstroLocaleExtendedConfig(defaultAstroLocale)
-						? defaultAstroLocale.codes[0]
-						: defaultAstroLocale,
-		},
-	};
-}
-
-/** Infer Starlight locale information based on a locale from an Astro i18n configuration. */
-function inferStarlightLocaleFromAstroLocale(astroLocale: AstroLocale) {
-	const lang = isAstroLocaleExtendedConfig(astroLocale) ? astroLocale.codes[0] : astroLocale;
-	return { ...getLocaleInfo(lang), lang };
-}
-
-/** Check if the passed locale is the default locale in an Astro i18n configuration. */
-function isDefaultAstroLocale(
-	astroI18nConfig: NonNullable<AstroConfig['i18n']>,
-	locale: AstroLocale
-) {
-	return (
-		(isAstroLocaleExtendedConfig(locale) ? locale.path : locale) === astroI18nConfig.defaultLocale
-	);
-}
-
-/**
- * Check if the passed Astro locale is using the object variant.
- * @see AstroLocaleExtendedConfig
- */
-function isAstroLocaleExtendedConfig(locale: AstroLocale): locale is AstroLocaleExtendedConfig {
-	return typeof locale !== 'string';
-}
-
-/** Returns the locale information such as a label and a direction based on a BCP-47 tag. */
-function getLocaleInfo(lang: string) {
-	try {
-		const locale = new Intl.Locale(lang);
-		const label = new Intl.DisplayNames(locale, { type: 'language' }).of(lang);
-		if (!label || lang === label) throw new Error('Label not found.');
-		return {
-			label: label[0]?.toLocaleUpperCase(locale) + label.slice(1),
-			dir: getLocaleDir(locale),
-		};
-	} catch {
-		throw new AstroError(
-			`Failed to get locale information for the '${lang}' locale.`,
-			'Make sure to provide a valid BCP-47 tags (e.g. en, ar, or zh-CN).'
-		);
-	}
-}
-
-/**
- * Returns the direction of the passed locale.
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo
- */
-function getLocaleDir(locale: Intl.Locale): 'ltr' | 'rtl' {
-	if ('textInfo' in locale) {
-		// @ts-expect-error - `textInfo` is not typed but is available in v8 based environments.
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-return
-		return locale.textInfo.direction;
-	} else if ('getTextInfo' in locale) {
-		// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-		// @ts-ignore - `getTextInfo` is not typed in older versions of TypeScript but is available in some browsers and newer versions of Node.
-		// TODO: remove or switch to @ts-expect-error in #3572
-		return locale.getTextInfo().direction;
-	}
-	// Firefox does not support `textInfo` or `getTextInfo` yet so we fallback to a well-known list
-	// of right-to-left languages.
-	// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-	// @ts-ignore — This is a type error with newer versions of TypeScript’s DOM types.
-	// TODO: remove or switch to @ts-expect-error in #3572
-	return wellKnownRTL.includes((locale as Intl.Locale).language) ? 'rtl' : 'ltr';
-}
-
-/**
- * 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'
- */
-export function pickLang<T extends Record<string, string>>(
-	dictionary: T,
-	lang: keyof T
-): string | undefined {
-	return dictionary[lang];
-}
-
-type AstroLocale = NonNullable<AstroConfig['i18n']>['locales'][number];
-type AstroLocaleExtendedConfig = Exclude<AstroLocale, string>;

package/utils/localizedUrl.ts

@@ -1,51 +0,0 @@
-import config from 'virtual:starlight/user-config';
-import { stripTrailingSlash } from './path';
-import type { AstroConfig } from 'astro';
-
-/**
- * Get the equivalent of the passed URL for the passed locale.
- */
-export function localizedUrl(
-	url: URL,
-	locale: string | undefined,
-	trailingSlash: AstroConfig['trailingSlash']
-): URL {
-	// Create a new URL object to void mutating the global.
-	url = new URL(url);
-	if (!config.locales) {
-		// i18n is not configured on this site, no localization required.
-		return url;
-	}
-	if (locale === 'root') locale = '';
-	/** Base URL with trailing `/` stripped. */
-	const base = stripTrailingSlash(import.meta.env.BASE_URL);
-	const hasBase = url.pathname.startsWith(base);
-	// Temporarily remove base to simplify
-	if (hasBase) url.pathname = url.pathname.replace(base, '');
-	const [_leadingSlash, baseSegment] = url.pathname.split('/');
-	// Strip .html extension to handle file output builds where URL might be e.g. `/en.html`
-	const htmlExt = '.html';
-	const isRootHtml = baseSegment?.endsWith(htmlExt);
-	const baseSlug = isRootHtml ? baseSegment?.slice(0, -1 * htmlExt.length) : baseSegment;
-	if (baseSlug && baseSlug in config.locales) {
-		// We’re in a localized route, substitute the new locale (or strip for root lang).
-		if (locale) {
-			url.pathname = url.pathname.replace(baseSlug, locale);
-		} else if (isRootHtml) {
-			url.pathname = '/index.html';
-		} else {
-			url.pathname = url.pathname.replace('/' + baseSlug, '');
-		}
-	} else if (locale) {
-		// We’re in the root language. Inject the new locale if we have one.
-		if (baseSegment === 'index.html') {
-			url.pathname = '/' + locale + '.html';
-		} else {
-			url.pathname = '/' + locale + url.pathname;
-		}
-	}
-	// Restore base
-	if (hasBase) url.pathname = base + url.pathname;
-	if (trailingSlash === 'never') url.pathname = stripTrailingSlash(url.pathname);
-	return url;
-}