@astrojs/starlight 0.10.4 → 0.11.0

package/utils/navigation.ts

@@ -5,9 +5,14 @@ import { pathWithBase } from './base';
 import { pickLang } from './i18n';
 import { getLocaleRoutes, type Route } from './routing';
 import { localeToLang, slugToPathname } from './slugs';
-import type { AutoSidebarGroup, SidebarItem, SidebarLinkItem } from './user-config';
 import { ensureLeadingAndTrailingSlashes, ensureTrailingSlash } from './path';
 import type { Badge } from '../schemas/badge';
+import type {
+	AutoSidebarGroup,
+	LinkHTMLAttributes,
+	SidebarItem,
+	SidebarLinkItem,
+} from '../schemas/sidebar';
 
 const DirKey = Symbol('DirKey');
 
@@ -17,6 +22,7 @@ export interface Link {
 	href: string;
 	isCurrent: boolean;
 	badge: Badge | undefined;
+	attrs: LinkHTMLAttributes;
 }
 
 interface Group {
@@ -114,14 +120,20 @@ function linkFromConfig(
 		if (locale) href = '/' + locale + href;
 	}
 	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
-	return makeLink(href, label, currentPathname, item.badge);
+	return makeLink(href, label, currentPathname, item.badge, item.attrs);
 }
 
 /** Create a link entry. */
-function makeLink(href: string, label: string, currentPathname: string, badge?: Badge): Link {
+function makeLink(
+	href: string,
+	label: string,
+	currentPathname: string,
+	badge?: Badge,
+	attrs?: LinkHTMLAttributes
+): Link {
 	if (!isAbsolute(href)) href = pathWithBase(href);
 	const isCurrent = href === ensureTrailingSlash(currentPathname);
-	return { type: 'link', label, href, isCurrent, badge };
+	return { type: 'link', label, href, isCurrent, badge, attrs: attrs ?? {} };
 }
 
 /** Get the segments leading to a page. */
@@ -171,7 +183,8 @@ function linkFromRoute(route: Route, currentPathname: string): Link {
 		slugToPathname(route.slug),
 		route.entry.data.sidebar.label || route.entry.data.title,
 		currentPathname,
-		route.entry.data.sidebar.badge
+		route.entry.data.sidebar.badge,
+		route.entry.data.sidebar.attrs
 	);
 }
 
@@ -274,7 +287,9 @@ export function getPrevNextLinks(
 		next?: PrevNextLinkConfig;
 	}
 ): {
+	/** Link to previous page in the sidebar. */
 	prev: Link | undefined;
+	/** Link to next page in the sidebar. */
 	next: Link | undefined;
 } {
 	const entries = flattenSidebar(sidebar);
@@ -308,6 +323,8 @@ function applyPrevNextLinkConfig(
 				...link,
 				label: config.label ?? link.label,
 				href: config.link ?? link.href,
+				// Explicitly remove sidebar link attributes for prev/next links.
+				attrs: {},
 			};
 		} else if (config.link && config.label) {
 			// If there is no link and the frontmatter contains both a URL and a label,

package/utils/route-data.ts

@@ -0,0 +1,97 @@
+import type { MarkdownHeading } from 'astro';
+import { fileURLToPath } from 'node:url';
+import project from 'virtual:starlight/project-context';
+import config from 'virtual:starlight/user-config';
+import { generateToC, type TocItem } from './generateToC';
+import { getFileCommitDate } from './git';
+import { getPrevNextLinks, getSidebar, type SidebarEntry } from './navigation';
+import type { Route } from './routing';
+import { useTranslations } from './translations';
+import { ensureTrailingSlash } from './path';
+
+interface PageProps extends Route {
+	headings: MarkdownHeading[];
+}
+
+export interface StarlightRouteData extends Route {
+	/** Array of Markdown headings extracted from the current page. */
+	headings: MarkdownHeading[];
+	/** Site navigation sidebar entries for this page. */
+	sidebar: SidebarEntry[];
+	/** Whether or not the sidebar should be displayed on this page. */
+	hasSidebar: boolean;
+	/** Links to the previous and next page in the sidebar if enabled. */
+	pagination: ReturnType<typeof getPrevNextLinks>;
+	/** Table of contents for this page if enabled. */
+	toc: { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined;
+	/** JS Date object representing when this page was last updated if enabled. */
+	lastUpdated: Date | undefined;
+	/** URL object for the address where this page can be edited if enabled. */
+	editUrl: URL | undefined;
+}
+
+export function generateRouteData({
+	props,
+	url,
+}: {
+	props: PageProps;
+	url: URL;
+}): StarlightRouteData {
+	const { entry, locale } = props;
+	const sidebar = getSidebar(url.pathname, locale);
+	return {
+		...props,
+		sidebar,
+		hasSidebar: entry.data.template !== 'splash',
+		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
+		toc: getToC(props),
+		lastUpdated: getLastUpdated(props),
+		editUrl: getEditUrl(props),
+	};
+}
+
+function getToC({ entry, locale, headings }: PageProps) {
+	const tocConfig =
+		entry.data.template === 'splash'
+			? false
+			: entry.data.tableOfContents !== undefined
+			? entry.data.tableOfContents
+			: config.tableOfContents;
+	if (!tocConfig) return;
+	const t = useTranslations(locale);
+	return {
+		...tocConfig,
+		items: generateToC(headings, { ...tocConfig, title: t('tableOfContents.overview') }),
+	};
+}
+
+function getLastUpdated({ entry, id }: PageProps): Date | undefined {
+	if (entry.data.lastUpdated ?? config.lastUpdated) {
+		const currentFilePath = fileURLToPath(new URL('src/content/docs/' + id, project.root));
+		let date = typeof entry.data.lastUpdated !== 'boolean' ? entry.data.lastUpdated : undefined;
+		if (!date) {
+			try {
+				({ date } = getFileCommitDate(currentFilePath, 'newest'));
+			} catch {}
+		}
+		return date;
+	}
+	return;
+}
+
+function getEditUrl({ entry, id }: PageProps): URL | undefined {
+	const { editUrl } = entry.data;
+	// If frontmatter value is false, editing is disabled for this page.
+	if (editUrl === false) return;
+
+	let url: string | undefined;
+	if (typeof editUrl === 'string') {
+		// If a URL was provided in frontmatter, use that.
+		url = editUrl;
+	} else if (config.editLink.baseUrl) {
+		const srcPath = project.srcDir.replace(project.root, '');
+		// If a base URL was added in Starlight config, synthesize the edit URL from it.
+		url = ensureTrailingSlash(config.editLink.baseUrl) + srcPath + 'content/docs/' + id;
+	}
+	return url ? new URL(url) : undefined;
+}

package/utils/routing.ts

@@ -8,16 +8,26 @@ import {
 	slugToLocaleData,
 	slugToParam,
 } from './slugs';
+import { validateLogoImports } from './validateLogoImports';
+
+// Validate any user-provided logos imported correctly.
+// We do this here so all pages trigger it and at the top level so it runs just once.
+validateLogoImports();
 
 export type StarlightDocsEntry = Omit<CollectionEntry<'docs'>, 'slug'> & {
 	slug: string;
 };
 
 export interface Route extends LocaleData {
+	/** Content collection entry for the current page. Includes frontmatter at `data`. */
 	entry: StarlightDocsEntry;
+	/** Locale metadata for the page content. Can be different from top-level locale values when a page is using fallback content. */
 	entryMeta: LocaleData;
+	/** The slug, a.k.a. permalink, for this page. */
 	slug: string;
+	/** The unique ID for this page. */
 	id: string;
+	/** True if this page is untranslated in the current language and using fallback content from the default locale. */
 	isFallback?: true;
 	[key: string]: unknown;
 }

package/utils/user-config.ts

@@ -1,10 +1,13 @@
 import { z } from 'astro/zod';
 import { parse as bcpParse, stringify as bcpStringify } from 'bcp-47';
+import { BadgeConfigSchema } from '../schemas/badge';
+import { ComponentConfigSchema } from '../schemas/components';
+import { FaviconSchema } from '../schemas/favicon';
 import { HeadConfigSchema } from '../schemas/head';
 import { LogoConfigSchema } from '../schemas/logo';
+import { SidebarItemSchema } from '../schemas/sidebar';
+import { SocialLinksSchema } from '../schemas/social';
 import { TableOfContentsSchema } from '../schemas/tableOfContents';
-import { FaviconSchema } from '../schemas/favicon';
-import { BadgeConfigSchema } from '../schemas/badge';
 
 const LocaleSchema = z.object({
 	/** The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`. */
@@ -28,79 +31,6 @@ const LocaleSchema = z.object({
 		),
 });
 
-const SidebarBaseSchema = z.object({
-	/** The visible label for this item in the sidebar. */
-	label: z.string(),
-	/** Translations of the `label` for each supported language. */
-	translations: z.record(z.string()).default({}),
-});
-
-const SidebarGroupSchema = SidebarBaseSchema.extend({
-	/** Whether this item should be collapsed by default. */
-	collapsed: z.boolean().default(false),
-});
-
-const SidebarLinkItemSchema = SidebarBaseSchema.extend({
-	/** The link to this item’s content. Can be a relative link to local files or the full URL of an external page. */
-	link: z.string(),
-	/** Adds a badge to the link item */
-	badge: BadgeConfigSchema(),
-});
-export type SidebarLinkItem = z.infer<typeof SidebarLinkItemSchema>;
-
-const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
-	/** Enable autogenerating a sidebar category from a specific docs directory. */
-	autogenerate: z.object({
-		/** The directory to generate sidebar items for. */
-		directory: z.string(),
-		/**
-		 * Whether the autogenerated subgroups should be collapsed by default.
-		 * Defaults to the `AutoSidebarGroup` `collapsed` value.
-		 */
-		collapsed: z.boolean().optional(),
-		// TODO: not supported by Docusaurus but would be good to have
-		/** How many directories deep to include from this directory in the sidebar. Default: `Infinity`. */
-		// depth: z.number().optional(),
-	}),
-});
-export type AutoSidebarGroup = z.infer<typeof AutoSidebarGroupSchema>;
-
-type ManualSidebarGroupInput = z.input<typeof SidebarGroupSchema> & {
-	/** Array of links and subcategories to display in this category. */
-	items: Array<
-		| z.input<typeof SidebarLinkItemSchema>
-		| z.input<typeof AutoSidebarGroupSchema>
-		| ManualSidebarGroupInput
-	>;
-};
-
-type ManualSidebarGroupOutput = z.output<typeof SidebarGroupSchema> & {
-	/** Array of links and subcategories to display in this category. */
-	items: Array<
-		| z.output<typeof SidebarLinkItemSchema>
-		| z.output<typeof AutoSidebarGroupSchema>
-		| ManualSidebarGroupOutput
-	>;
-};
-
-const ManualSidebarGroupSchema: z.ZodType<
-	ManualSidebarGroupOutput,
-	z.ZodTypeDef,
-	ManualSidebarGroupInput
-> = SidebarGroupSchema.extend({
-	/** Array of links and subcategories to display in this category. */
-	items: z.lazy(() =>
-		z.union([SidebarLinkItemSchema, ManualSidebarGroupSchema, AutoSidebarGroupSchema]).array()
-	),
-});
-
-const SidebarItemSchema = z.union([
-	SidebarLinkItemSchema,
-	ManualSidebarGroupSchema,
-	AutoSidebarGroupSchema,
-]);
-export type SidebarItem = z.infer<typeof SidebarItemSchema>;
-
 const UserConfigSchema = z.object({
 	/** Title for your website. Will be used in metadata and as browser tab title. */
 	title: z
@@ -133,33 +63,7 @@ const UserConfigSchema = z.object({
 	 *   youtube: 'https://youtube.com/@astrodotbuild',
 	 * }
 	 */
-	social: z
-		.record(
-			z.enum([
-				'twitter',
-				'mastodon',
-				'github',
-				'gitlab',
-				'bitbucket',
-				'discord',
-				'gitter',
-				'codeberg',
-				'codePen',
-				'youtube',
-				'threads',
-				'linkedin',
-				'twitch',
-				'microsoftTeams',
-				'instagram',
-				'stackOverflow',
-				'x.com',
-				'telegram',
-				'rss',
-			]),
-			// Link to the respective social profile for this site
-			z.string().url()
-		)
-		.optional(),
+	social: SocialLinksSchema(),
 
 	/** The tagline for your website. */
 	tagline: z.string().optional().describe('The tagline for your website.'),
@@ -279,6 +183,15 @@ const UserConfigSchema = z.object({
 
 	/** The default favicon for your site which should be a path to an image in the `public/` directory. */
 	favicon: FaviconSchema(),
+
+	/** Specify paths to components that should override Starlight’s default components */
+	components: ComponentConfigSchema(),
+
+	/** Will be used as title delimiter in the generated `<title>` tag. */
+	titleDelimiter: z
+		.string()
+		.default('|')
+		.describe('Will be used as title delimiter in the generated `<title>` tag.'),
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(

package/utils/validateLogoImports.ts

@@ -0,0 +1,21 @@
+import config from 'virtual:starlight/user-config';
+import { logos } from 'virtual:starlight/user-images';
+
+/** Check user-imported logo images have resolved correctly. */
+export function validateLogoImports(): void {
+	if (config.logo) {
+		let err: string | undefined;
+		if ('src' in config.logo) {
+			if (!logos.dark || !logos.light) {
+				err = `Could not resolve logo import for "${config.logo.src}" (logo.src)`;
+			}
+		} else {
+			if (!logos.dark) {
+				err = `Could not resolve logo import for "${config.logo.dark}" (logo.dark)`;
+			} else if (!logos.light) {
+				err = `Could not resolve logo import for "${config.logo.light}" (logo.light)`;
+			}
+		}
+		if (err) throw new Error(err);
+	}
+}

package/virtual.d.ts

@@ -15,3 +15,40 @@ declare module 'virtual:starlight/user-images' {
 		light?: ImageMetadata;
 	};
 }
+
+declare module 'virtual:starlight/components' {
+	export const Banner: typeof import('./components/Banner.astro').default;
+	export const ContentPanel: typeof import('./components/ContentPanel.astro').default;
+	export const PageTitle: typeof import('./components/PageTitle.astro').default;
+	export const FallbackContentNotice: typeof import('./components/FallbackContentNotice.astro').default;
+
+	export const Footer: typeof import('./components/Footer.astro').default;
+	export const LastUpdated: typeof import('./components/LastUpdated.astro').default;
+	export const Pagination: typeof import('./components/Pagination.astro').default;
+	export const EditLink: typeof import('./components/EditLink.astro').default;
+
+	export const Header: typeof import('./components/Header.astro').default;
+	export const LanguageSelect: typeof import('./components/LanguageSelect.astro').default;
+	export const Search: typeof import('./components/Search.astro').default;
+	export const SiteTitle: typeof import('./components/SiteTitle.astro').default;
+	export const SocialIcons: typeof import('./components/SocialIcons.astro').default;
+	export const ThemeSelect: typeof import('./components/ThemeSelect.astro').default;
+
+	export const Head: typeof import('./components/Head.astro').default;
+	export const Hero: typeof import('./components/Hero.astro').default;
+	export const MarkdownContent: typeof import('./components/MarkdownContent.astro').default;
+
+	export const PageSidebar: typeof import('./components/PageSidebar.astro').default;
+	export const TableOfContents: typeof import('./components/TableOfContents.astro').default;
+	export const MobileTableOfContents: typeof import('./components/MobileTableOfContents.astro').default;
+
+	export const Sidebar: typeof import('./components/Sidebar.astro').default;
+	export const SkipLink: typeof import('./components/SkipLink.astro').default;
+	export const ThemeProvider: typeof import('./components/ThemeProvider.astro').default;
+
+	export const PageFrame: typeof import('./components/PageFrame.astro').default;
+	export const MobileMenuToggle: typeof import('./components/MobileMenuToggle.astro').default;
+	export const MobileMenuFooter: typeof import('./components/MobileMenuFooter.astro').default;
+
+	export const TwoColumnContent: typeof import('./components/TwoColumnContent.astro').default;
+}

package/components/RightSidebar.astro

@@ -1,36 +0,0 @@
----
-import type { MarkdownHeading } from 'astro';
-import RightSidebarPanel from './RightSidebarPanel.astro';
-import MobileTableOfContents from './TableOfContents/MobileTableOfContents.astro';
-import TableOfContents from './TableOfContents.astro';
-import { generateToC } from './TableOfContents/generateToC';
-import { useTranslations } from '../utils/translations';
-
-interface Props {
-	headings: MarkdownHeading[];
-	locale: string | undefined;
-	tocConfig: { maxHeadingLevel: number; minHeadingLevel: number } | false;
-}
-
-const { headings, locale, tocConfig } = Astro.props;
-const t = useTranslations(locale);
-const tocProps = tocConfig && {
-	...tocConfig,
-	locale,
-	toc: generateToC(headings, {
-		...tocConfig,
-		title: t('tableOfContents.overview'),
-	}),
-};
----
-
-{
-	tocProps && (
-		<>
-			<MobileTableOfContents {...tocProps} />
-			<RightSidebarPanel>
-				<TableOfContents {...tocProps} />
-			</RightSidebarPanel>
-		</>
-	)
-}

package/layout/Page.astro

@@ -1,132 +0,0 @@
----
-import config from 'virtual:starlight/user-config';
-import type { MarkdownHeading } from 'astro';
-import { getSidebar } from '../utils/navigation';
-import type { Route } from '../utils/routing';
-
-// Built-in CSS styles.
-import '../style/props.css';
-import '../style/reset.css';
-import '../style/shiki.css';
-import '../style/util.css';
-
-// Components — can override built-in CSS, but not user CSS.
-import ContentPanel from '../components/ContentPanel.astro';
-import FallbackContentNotice from '../components/FallbackContentNotice.astro';
-import Footer from '../components/Footer.astro';
-import HeadSEO from '../components/HeadSEO.astro';
-import Header from '../components/Header.astro';
-import Hero from '../components/Hero.astro';
-import MarkdownContent from '../components/MarkdownContent.astro';
-import RightSidebar from '../components/RightSidebar.astro';
-import Sidebar from '../components/Sidebar.astro';
-import SkipLink from '../components/SkipLink.astro';
-import ThemeProvider from '../components/ThemeProvider.astro';
-import PageFrame from '../layout/PageFrame.astro';
-import TwoColumnContent from '../layout/TwoColumnContent.astro';
-import Banner from '../components/Banner.astro';
-
-// Remark component CSS (needs to override `MarkdownContent.astro`)
-import '../style/asides.css';
-
-// Important that this is the last import so it can override built-in styles.
-import 'virtual:starlight/user-css';
-
-type Props = Route & { headings: MarkdownHeading[] };
-
-const { dir, entry, entryMeta, headings, isFallback, lang, locale } = Astro.props;
-const sidebar = getSidebar(Astro.url.pathname, locale);
-
-const hasSidebar = entry.data.template !== 'splash';
-const tocConfig = !hasSidebar
-	? false
-	: entry.data.tableOfContents !== undefined
-	? entry.data.tableOfContents
-	: config.tableOfContents;
-const hasToC = Boolean(tocConfig);
-const hasHero = Boolean(entry.data.hero);
-const pagefindEnabled =
-	entry.slug !== '404' && !entry.slug.endsWith('/404') && entry.data.pagefind !== false;
----
-
-<html
-	lang={lang}
-	dir={dir}
-	data-has-toc={hasToC}
-	data-has-sidebar={hasSidebar}
-	data-has-hero={hasHero}
->
-	<head>
-		<HeadSEO data={entry.data} lang={lang} />
-		<style>
-			html:not([data-has-toc]) {
-				--sl-mobile-toc-height: 0rem;
-			}
-			html:not([data-has-sidebar]) {
-				--sl-content-width: 67.5rem;
-			}
-			/* Add scroll padding to ensure anchor headings aren't obscured by nav */
-			html {
-				/* Additional padding is needed to account for the mobile TOC */
-				scroll-padding-top: calc(1.5rem + var(--sl-nav-height) + var(--sl-mobile-toc-height));
-			}
-			main {
-				padding-bottom: 3vh;
-			}
-			@media (min-width: 50em) {
-				[data-has-sidebar] {
-					--sl-content-inline-start: var(--sl-sidebar-width);
-				}
-			}
-			@media (min-width: 72em) {
-				html {
-					scroll-padding-top: calc(1.5rem + var(--sl-nav-height));
-				}
-			}
-		</style>
-	</head>
-	<body>
-		<ThemeProvider />
-		<SkipLink {locale} />
-		<PageFrame {locale} {hasSidebar}>
-			<Header slot="header" {locale} />
-			{hasSidebar && <Sidebar slot="sidebar" {sidebar} {locale} />}
-			<TwoColumnContent {hasToC}>
-				<RightSidebar slot="right-sidebar" {headings} {locale} {tocConfig} />
-				<main data-pagefind-body={pagefindEnabled} lang={entryMeta.lang} dir={entryMeta.dir}>
-					{/* TODO: Revisit how this logic flows. */}
-					{entry.data.banner && <Banner {...entry.data.banner} />}
-					{
-						entry.data.hero ? (
-							<ContentPanel>
-								<Hero hero={entry.data.hero} fallbackTitle={entry.data.title} />
-								<MarkdownContent>
-									<slot />
-								</MarkdownContent>
-							</ContentPanel>
-						) : (
-							<>
-								<ContentPanel>
-									<h1
-										id="_top"
-										data-page-title
-										style="font-size: var(--sl-text-h1); line-height: var(--sl-line-height-headings); font-weight: 600; color: var(--sl-color-white); margin-top: 1rem;"
-									>
-										{entry.data.title}
-									</h1>
-									{isFallback && <FallbackContentNotice {locale} />}
-								</ContentPanel>
-								<ContentPanel>
-									<MarkdownContent>
-										<slot />
-									</MarkdownContent>
-									<Footer {...{ entry, dir, lang, locale, sidebar }} />
-								</ContentPanel>
-							</>
-						)
-					}
-				</main>
-			</TwoColumnContent>
-		</PageFrame>
-	</body>
-</html>