@astrojs/starlight 0.21.4 → 0.22.0

package/translations/vi.json

@@ -18,6 +18,7 @@
   "page.lastUpdated": "Cập nhật lần cuối:",
   "page.previousLink": "Tiếp",
   "page.nextLink": "Trước",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Không tìm thấy trang. Kiểm tra URL hoặc thử sử dụng thanh tìm kiếm.",
   "aside.note": "Ghi chú",
   "aside.tip": "Mẹo",

package/translations/zh-CN.json

@@ -18,6 +18,7 @@
   "page.lastUpdated": "最近更新：",
   "page.previousLink": "上一页",
   "page.nextLink": "下一页",
+  "page.draft": "此内容为草稿，不会包含在生产版本中。",
   "404.text": "页面未找到。检查 URL 或尝试使用搜索栏。",
   "aside.note": "注意",
   "aside.tip": "提示",

package/translations/zh-TW.json

@@ -18,6 +18,7 @@
   "page.lastUpdated": "最後更新於：",
   "page.previousLink": "前一則",
   "page.nextLink": "下一則",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "找不到頁面。請檢查網址或改用搜尋功能。",
   "aside.note": "注意",
   "aside.tip": "提示",

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">
@@ -17,7 +22,7 @@ const { html, panels } = processPanels(panelHtml);
 								role="tab"
 								href={'#' + panelId}
 								id={tabId}
-								aria-selected={idx === 0 && 'true'}
+								aria-selected={idx === 0 ? 'true' : 'false'}
 								tabindex={idx !== 0 ? -1 : 0}
 							>
 								{icon && <Icon name={icon} />}
@@ -61,7 +66,7 @@ const { html, panels } = processPanels(panelHtml);
 		color: var(--sl-color-gray-3);
 		outline-offset: var(--sl-outline-offset-inside);
 	}
-	.tab [role='tab'][aria-selected] {
+	.tab [role='tab'][aria-selected='true'] {
 		color: var(--sl-color-white);
 		border-color: var(--sl-color-text-accent);
 		font-weight: 600;
@@ -74,20 +79,31 @@ 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
 				tab.addEventListener('click', (e) => {
 					e.preventDefault();
-					const currentTab = tablist.querySelector('[aria-selected]');
+					const currentTab = tablist.querySelector('[aria-selected="true"]');
 					if (e.currentTarget !== currentTab) {
 						this.switchTab(e.currentTarget as HTMLAnchorElement, i);
 					}
@@ -117,12 +133,17 @@ 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.removeAttribute('aria-selected');
+				tab.setAttribute('aria-selected', 'false');
 				tab.setAttribute('tabindex', '-1');
 			});
 			this.panels.forEach((oldPanel) => {
@@ -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/user-components/file-tree-icons.ts

@@ -113,6 +113,7 @@ export const definitions: Definitions = {
 	extensions: {
 		'.astro': 'astro',
 		'.mdx': 'mdx',
+		'.pkl': 'pkl',
 		'.bsl': 'seti:bsl',
 		'.mdo': 'seti:mdo',
 		'.cls': 'seti:salesforce',

package/user-components/rehype-file-tree.ts

@@ -168,7 +168,7 @@ function getFileIcon(fileName: string) {
 
 /** Return the icon name for a file based on its file name. */
 function getFileIconName(fileName: string) {
-	let icon = definitions.files[fileName];
+	let icon: string | undefined = definitions.files[fileName];
 	if (icon) return icon;
 	icon = getFileIconTypeFromExtension(fileName);
 	if (icon) return icon;

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. **/
+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/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,17 +210,21 @@ const UserConfigSchema = z.object({
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(
-	({ locales, defaultLocale, ...config }, ctx) => {
-		if (locales !== undefined && Object.keys(locales).length > 1) {
-			// This is a multilingual site (more than one locale configured).
+	({ 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
+		// only one locale configured (not a root locale).
+		// Monolingual sites with only one non-root locale needs their configuration to be defined in
+		// `config.locales` so that slugs can be correctly generated by taking into consideration the
+		// base path at which a language is served which is the key of the `config.locales` object.
+		if (locales !== undefined && configuredLocales.length >= 1) {
 			// Make sure we can find the default locale and if not, help the user set it.
 			// We treat the root locale as the default if present and no explicit default is set.
 			const defaultLocaleConfig = locales[defaultLocale || 'root'];
 
 			if (!defaultLocaleConfig) {
-				const availableLocales = Object.keys(locales)
-					.map((l) => `"${l}"`)
-					.join(', ');
+				const availableLocales = configuredLocales.map((l) => `"${l}"`).join(', ');
 				ctx.addIssue({
 					code: 'custom',
 					message:
@@ -232,29 +235,40 @@ 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: true,
+				isMultilingual: configuredLocales.length > 1,
 				/** Full locale object for this site’s default language. */
 				defaultLocale: { ...defaultLocaleConfig, locale: defaultLocale },
 				locales,
 			} as const;
 		}
 
-		// This is a monolingual site, so things are pretty simple.
+		// 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;