@astrojs/starlight 0.21.5 → 0.22.1

package/user-components/Tabs.astro

@@ -2,11 +2,16 @@
 import Icon from './Icon.astro';
 import { processPanels } from './rehype-tabs';
 
+interface Props {
+	syncKey?: string;
+}
+
+const { syncKey } = Astro.props;
 const panelHtml = await Astro.slots.render('default');
 const { html, panels } = processPanels(panelHtml);
 ---
 
-<starlight-tabs>
+<starlight-tabs data-sync-key={syncKey}>
 	{
 		panels && (
 			<div class="tablist-wrapper not-content">
@@ -74,14 +79,25 @@ const { html, panels } = processPanels(panelHtml);
 
 <script>
 	class StarlightTabs extends HTMLElement {
+		// A map of sync keys to all tabs that are synced to that key.
+		static #syncedTabs = new Map<string, StarlightTabs[]>();
+
 		tabs: HTMLAnchorElement[];
 		panels: HTMLElement[];
+		#syncKey: string | undefined;
 
 		constructor() {
 			super();
 			const tablist = this.querySelector<HTMLUListElement>('[role="tablist"]')!;
 			this.tabs = [...tablist.querySelectorAll<HTMLAnchorElement>('[role="tab"]')];
 			this.panels = [...this.querySelectorAll<HTMLElement>(':scope > [role="tabpanel"]')];
+			this.#syncKey = this.dataset.syncKey;
+
+			if (this.#syncKey) {
+				const syncedTabs = StarlightTabs.#syncedTabs.get(this.#syncKey) ?? [];
+				syncedTabs.push(this);
+				StarlightTabs.#syncedTabs.set(this.#syncKey, syncedTabs);
+			}
 
 			this.tabs.forEach((tab, i) => {
 				// Handle clicks for mouse users
@@ -117,9 +133,14 @@ const { html, panels } = processPanels(panelHtml);
 			});
 		}
 
-		switchTab(newTab: HTMLAnchorElement | null | undefined, index: number) {
+		switchTab(newTab: HTMLAnchorElement | null | undefined, index: number, shouldSync = true) {
 			if (!newTab) return;
 
+			// If tabs should be synced, we store the current position so we can restore it after
+			// switching tabs to prevent the page from jumping when the new tab content is of a different
+			// height than the previous tab.
+			const previousTabsOffset = shouldSync ? this.getBoundingClientRect().top : 0;
+
 			// Mark all tabs as unselected and hide all tab panels.
 			this.tabs.forEach((tab) => {
 				tab.setAttribute('aria-selected', 'false');
@@ -135,7 +156,27 @@ const { html, panels } = processPanels(panelHtml);
 			// Restore active tab to the default tab order.
 			newTab.removeAttribute('tabindex');
 			newTab.setAttribute('aria-selected', 'true');
-			newTab.focus();
+			if (shouldSync) {
+				newTab.focus();
+				StarlightTabs.#syncTabs(this, newTab.textContent);
+				window.scrollTo({
+					top: window.scrollY + (this.getBoundingClientRect().top - previousTabsOffset),
+				});
+			}
+		}
+
+		static #syncTabs(emitter: StarlightTabs, label: string | null) {
+			const syncKey = emitter.#syncKey;
+			if (!syncKey || !label) return;
+			const syncedTabs = StarlightTabs.#syncedTabs.get(syncKey);
+			if (!syncedTabs) return;
+
+			for (const receiver of syncedTabs) {
+				if (receiver === emitter) continue;
+				const labelIndex = receiver.tabs.findIndex((tab) => tab.textContent === label);
+				if (labelIndex === -1) continue;
+				receiver.switchTab(receiver.tabs[labelIndex], labelIndex, false);
+			}
 		}
 	}
 

package/utils/createTranslationSystem.ts

@@ -2,8 +2,8 @@ import type { i18nSchemaOutput } from '../schemas/i18n';
 import builtinTranslations from '../translations/index';
 import type { StarlightConfig } from './user-config';
 
-export function createTranslationSystem(
-	userTranslations: Record<string, i18nSchemaOutput>,
+export function createTranslationSystem<T extends i18nSchemaOutput>(
+	userTranslations: Record<string, T>,
 	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>
 ) {
 	/** User-configured default locale. */
@@ -67,18 +67,20 @@ function localeToLang(
 	return lang || defaultLang || 'en';
 }
 
+type BuiltInStrings = (typeof builtinTranslations)['en'];
+
 /** Build a dictionary by layering preferred translation sources. */
-function buildDictionary(
-	base: (typeof builtinTranslations)[string],
-	...dictionaries: (i18nSchemaOutput | undefined)[]
-) {
+function buildDictionary<T extends Record<string, string | undefined>>(
+	base: BuiltInStrings,
+	...dictionaries: (T | BuiltInStrings | undefined)[]
+): BuiltInStrings & T {
 	const dictionary = { ...base };
 	// Iterate over alternate dictionaries to avoid overwriting preceding values with `undefined`.
 	for (const dict of dictionaries) {
 		for (const key in dict) {
-			const value = dict[key];
+			const value = dict[key as keyof typeof dict];
 			if (value) dictionary[key as keyof typeof dictionary] = value;
 		}
 	}
-	return dictionary;
+	return dictionary as BuiltInStrings & T;
 }

package/utils/route-data.ts

@@ -15,6 +15,8 @@ export interface PageProps extends Route {
 }
 
 export interface StarlightRouteData extends Route {
+	/** Title of the site. */
+	siteTitle: string;
 	/** Array of Markdown headings extracted from the current page. */
 	headings: MarkdownHeading[];
 	/** Site navigation sidebar entries for this page. */
@@ -40,10 +42,12 @@ export function generateRouteData({
 	props: PageProps;
 	url: URL;
 }): StarlightRouteData {
-	const { entry, locale } = props;
+	const { entry, locale, lang } = props;
 	const sidebar = getSidebar(url.pathname, locale);
+	const siteTitle = getSiteTitle(lang);
 	return {
 		...props,
+		siteTitle,
 		sidebar,
 		hasSidebar: entry.data.template !== 'splash',
 		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
@@ -105,3 +109,12 @@ function getEditUrl({ entry, id, isFallback }: PageProps): URL | undefined {
 	}
 	return url ? new URL(url) : undefined;
 }
+
+/** Get the site title for a given language. **/
+export function getSiteTitle(lang: string): string {
+	const defaultLang = config.defaultLocale.lang as string;
+	if (lang && config.title[lang]) {
+		return config.title[lang] as string;
+	}
+	return config.title[defaultLang] as string;
+}

package/utils/routing.ts

@@ -45,12 +45,15 @@ interface Path extends GetStaticPathsItem {
 const normalizeIndexSlug = (slug: string) => (slug === 'index' ? '' : slug);
 
 /** All entries in the docs content collection. */
-const docs: StarlightDocsEntry[] = ((await getCollection('docs')) ?? []).map(
-	({ slug, ...entry }) => ({
-		...entry,
-		slug: normalizeIndexSlug(slug),
-	})
-);
+const docs: StarlightDocsEntry[] = (
+	(await getCollection('docs', ({ data }) => {
+		// In production, filter out drafts.
+		return import.meta.env.MODE !== 'production' || data.draft === false;
+	})) ?? []
+).map(({ slug, ...entry }) => ({
+	...entry,
+	slug: normalizeIndexSlug(slug),
+}));
 
 function getRoutes(): Route[] {
 	const routes: Route[] = docs.map((entry) => ({

package/utils/starlight-page.ts

@@ -3,7 +3,7 @@ import { type ContentConfig, type SchemaContext } from 'astro:content';
 import config from 'virtual:starlight/user-config';
 import { parseWithFriendlyErrors } from './error-map';
 import { stripLeadingAndTrailingSlashes } from './path';
-import { getToC, type PageProps, type StarlightRouteData } from './route-data';
+import { getSiteTitle, getToC, type PageProps, type StarlightRouteData } from './route-data';
 import type { StarlightDocsEntry } from './routing';
 import { slugToLocaleData, urlToSlug } from './slugs';
 import { getPrevNextLinks, getSidebar } from './navigation';
@@ -223,6 +223,7 @@ export async function generateStarlightPageRouteData({
 		lastUpdated,
 		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
 		sidebar,
+		siteTitle: getSiteTitle(localeData.lang),
 		slug,
 		toc: getToC({
 			...routeProps,

package/utils/translations.ts

@@ -1,11 +1,15 @@
-import { getCollection } from 'astro:content';
+import { getCollection, type CollectionEntry, type DataCollectionKey } from 'astro:content';
 import config from 'virtual:starlight/user-config';
 import type { i18nSchemaOutput } from '../schemas/i18n';
 import { createTranslationSystem } from './createTranslationSystem';
 
+type UserI18nSchema = 'i18n' extends DataCollectionKey
+	? CollectionEntry<'i18n'>['data']
+	: i18nSchemaOutput;
+
 /** Get all translation data from the i18n collection, keyed by `id`, which matches locale. */
 async function loadTranslations() {
-	let userTranslations: Record<string, i18nSchemaOutput> = {};
+	let userTranslations: Record<string, UserI18nSchema> = {};
 	// Briefly override `console.warn()` to silence logging when a project has no i18n collection.
 	const warn = console.warn;
 	console.warn = () => {};

package/utils/user-config.ts

@@ -8,6 +8,7 @@ import { LogoConfigSchema } from '../schemas/logo';
 import { SidebarItemSchema } from '../schemas/sidebar';
 import { SocialLinksSchema } from '../schemas/social';
 import { TableOfContentsSchema } from '../schemas/tableOfContents';
+import { TitleConfigSchema, TitleTransformConfigSchema } from '../schemas/site-title';
 
 const LocaleSchema = z.object({
 	/** The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`. */
@@ -33,9 +34,7 @@ const LocaleSchema = z.object({
 
 const UserConfigSchema = z.object({
 	/** Title for your website. Will be used in metadata and as browser tab title. */
-	title: z
-		.string()
-		.describe('Title for your website. Will be used in metadata and as browser tab title.'),
+	title: TitleConfigSchema(),
 
 	/** Description metadata for your website. Can be used in page metadata. */
 	description: z
@@ -211,7 +210,7 @@ const UserConfigSchema = z.object({
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(
-	({ locales, defaultLocale, ...config }, ctx) => {
+	({ title, locales, defaultLocale, ...config }, ctx) => {
 		const configuredLocales = Object.keys(locales ?? {});
 
 		// This is a multilingual site (more than one locale configured) or a monolingual site with
@@ -236,8 +235,13 @@ export const StarlightConfigSchema = UserConfigSchema.strict().transform(
 				return z.NEVER;
 			}
 
+			// Transform the title
+			const TitleSchema = TitleTransformConfigSchema(defaultLocaleConfig.lang as string);
+			const parsedTitle = TitleSchema.parse(title);
+
 			return {
 				...config,
+				title: parsedTitle,
 				/** Flag indicating if this site has multiple locales set up. */
 				isMultilingual: configuredLocales.length > 1,
 				/** Full locale object for this site’s default language. */
@@ -248,18 +252,23 @@ export const StarlightConfigSchema = UserConfigSchema.strict().transform(
 
 		// This is a monolingual site with no locales configured or only a root locale, so things are
 		// pretty simple.
+		/** Full locale object for this site’s default language. */
+		const defaultLocaleConfig = {
+			label: 'English',
+			lang: 'en',
+			dir: 'ltr',
+			locale: undefined,
+			...locales?.root,
+		};
+		/** Transform the title */
+		const TitleSchema = TitleTransformConfigSchema(defaultLocaleConfig.lang);
+		const parsedTitle = TitleSchema.parse(title);
 		return {
 			...config,
+			title: parsedTitle,
 			/** Flag indicating if this site has multiple locales set up. */
 			isMultilingual: false,
-			/** Full locale object for this site’s default language. */
-			defaultLocale: {
-				label: 'English',
-				lang: 'en',
-				dir: 'ltr',
-				locale: undefined,
-				...locales?.root,
-			},
+			defaultLocale: defaultLocaleConfig,
 			locales: undefined,
 		} as const;
 	}

package/virtual.d.ts

@@ -44,6 +44,10 @@ declare module 'virtual:starlight/components/FallbackContentNotice' {
 	const FallbackContentNotice: typeof import('./components/FallbackContentNotice.astro').default;
 	export default FallbackContentNotice;
 }
+declare module 'virtual:starlight/components/DraftContentNotice' {
+	const DraftContentNotice: typeof import('./components/DraftContentNotice.astro').default;
+	export default DraftContentNotice;
+}
 
 declare module 'virtual:starlight/components/Footer' {
 	const Footer: typeof import('./components/Footer.astro').default;