@astrojs/starlight 0.28.6 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @astrojs/starlight
 
+## 0.29.0
+
+### Minor Changes
+
+- [#2551](https://github.com/withastro/starlight/pull/2551) [`154c8e3`](https://github.com/withastro/starlight/commit/154c8e337819c7d7ebf4ff4dd55db0d10607620b) Thanks [@hippotastic](https://github.com/hippotastic)! - Updates the `astro-expressive-code` dependency to the latest version (0.38).
+
+  The new version allows using `ec.config.mjs` to selectively override individual Expressive Code styles and settings provided by Starlight themes and plugins, speeds up Shiki language loading, and adds the config option `expressiveCode.shiki.injectLangsIntoNestedCodeBlocks`. See the [Expressive Code release notes](https://expressive-code.com/releases/#0380) for full details.
+
+- [#2252](https://github.com/withastro/starlight/pull/2252) [`6116db0`](https://github.com/withastro/starlight/commit/6116db03a4157c0f0caa210690ef0dcdd001a287) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Improves build performance for sites with large sidebars
+
+  This release adds a caching layer to Starlight’s sidebar generation logic, reducing the number of times sidebars need to be regenerated while building a site. Some benchmarks for projects with a complex sidebar saw builds complete more than 35% faster with this change.
+
+- [#2503](https://github.com/withastro/starlight/pull/2503) [`a4c8edd`](https://github.com/withastro/starlight/commit/a4c8eddc53993068c0f60159fecc123013827ef0) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Improves the accessibility of asides and tabs by removing some unnecessary HTML landmarks.
+
+### Patch Changes
+
+- [#2579](https://github.com/withastro/starlight/pull/2579) [`241966b`](https://github.com/withastro/starlight/commit/241966bd0523a2e82891d622b2a97b2f3646bc41) Thanks [@RafidMuhymin](https://github.com/RafidMuhymin)! - Adds social link icon for Nostr
+
 ## 0.28.6
 
 ### Patch Changes

package/components/Icons.ts

@@ -158,6 +158,8 @@ export const BuiltInIcons = {
 		'<path d="M6.49 19.04h-.23L5.13 17.9v-.23l1.73-1.71h1.2l.15.15v1.2L6.5 19.04ZM5.13 6.31V6.1l1.13-1.13h.23L8.2 6.68v1.2l-.15.15h-1.2zm9.96 9.09h-1.65l-.14-.13v-3.83c0-.68-.27-1.2-1.1-1.23c-.42 0-.9 0-1.43.02l-.07.08v4.96l-.14.14H8.9l-.13-.14V8.73l.13-.14h3.7a2.6 2.6 0 0 1 2.61 2.6v4.08l-.13.14Zm-8.37-2.44H.14L0 12.82v-1.64l.14-.14h6.58l.14.14v1.64zm17.14 0h-6.58l-.14-.14v-1.64l.14-.14h6.58l.14.14v1.64zM11.05 6.55V1.64l.14-.14h1.65l.14.14v4.9l-.14.14h-1.65zm0 15.81v-4.9l.14-.14h1.65l.14.13v4.91l-.14.14h-1.65z"/>',
 	deno: '<path d="M12 0a12 12 0 1 1 0 24 12 12 0 0 1 0-24m-.47 6.8c-3.49 0-6.2 2.19-6.2 4.92 0 2.58 2.5 4.23 6.37 4.15h.12l.42-.02-.1.28v.03l.09.22v.03l.02.04.02.07.02.04.01.05.02.05.02.07.02.08.02.06.02.08.02.09.02.09.03.1.01.06.03.1.02.1.03.15.02.07.02.11.03.12.02.12.04.17.02.15.04.2.02.1.03.15.03.15.04.22.04.23.04.23.04.24.04.24.04.26.04.26.04.2.05.34.02.14.06.36.04.3.04.22.04.31.03.16a10.76 10.76 0 0 0 6.53-3.41l.05-.06-.24-.89-.64-2.37-.39-1.47-.35-1.3-.21-.78-.14-.5-.08-.3-.07-.26-.03-.11-.02-.07-.01-.03v-.03a6.04 6.04 0 0 0-2.05-2.97 6.75 6.75 0 0 0-4.25-1.35M8.47 19.3a.59.59 0 0 0-.72.4v.01l-.53 1.96q.5.24 1.01.43l.08.03.57-2.11V20a.59.59 0 0 0-.41-.7m3.26-1.43a.59.59 0 0 0-.71.4v.01l-.8 2.96v.01a.59.59 0 0 0 1.12.3l.8-2.96v-.02l.02-.06v-.02l-.02-.1-.02-.14-.02-.08a.58.58 0 0 0-.37-.3Zm-5.55-3.04a1 1 0 0 0-.04.09v.02l-.8 2.95v.02a.59.59 0 0 0 1.13.3v-.01l.72-2.68a5.3 5.3 0 0 1-1.01-.7Zm-1.9-3.4a.59.59 0 0 0-.72.4v.02l-.8 2.95v.01a.59.59 0 0 0 1.13.3l.8-2.96v-.01a.59.59 0 0 0-.41-.7m17.87-.68a.59.59 0 0 0-.72.4v.02l-.8 2.95v.01a.59.59 0 0 0 1.13.3l.8-2.96v-.01a.59.59 0 0 0-.41-.7M2.55 6.81a10.7 10.7 0 0 0-1.26 3.93.59.59 0 0 0 1-.22v-.02l.8-2.95v-.01a.59.59 0 0 0-.55-.73m17.59.02a.59.59 0 0 0-.72.4v.01l-.8 2.96v.01a.59.59 0 0 0 1.13.3l.8-2.96v-.01a.59.59 0 0 0-.41-.7Zm-7.85 1.93a.75.75 0 1 1 0 1.5.75.75 0 0 1 0-1.5M6.01 4.03a.59.59 0 0 0-.71.4v.02L4.5 7.4v.01a.59.59 0 0 0 1.12.3l.8-2.96v-.01a.59.59 0 0 0-.41-.7Zm10.24.56a.59.59 0 0 0-.71.4V5L15 7q.52.26.99.6l.05.04.62-2.32V5.3a.59.59 0 0 0-.41-.7m-5.21-3.34a11 11 0 0 0-1.12.16l-.07.01L9.1 4.2v.01a.59.59 0 0 0 1.13.3l.8-2.96v-.01a.6.6 0 0 0 0-.27m7.34 2.04-.16.58v.02a.59.59 0 0 0 1.13.3V4.2l.02-.07a11 11 0 0 0-.92-.77zm-4.64-1.94-.28 1.05a.59.59 0 0 0 1.13.31v-.01l.3-1.1q-.52-.15-1.06-.24z"/>',
 	jsr: '<path d="M3.7 5.54v3.7H0v7.38h7.38v1.84h12.93v-3.7H24V7.39h-7.38V5.54Zm1.84 1.85h1.85v7.38H1.84v-3.7h1.84v1.85h1.85zm3.7 0h5.53v1.84h-3.7v1.85h3.7v5.53H9.23v-1.84h3.7v-1.85h-3.7Zm7.38 1.84h5.53v3.7h-1.84v-1.85h-1.85v5.54h-1.84z"/>',
+	nostr:
+		'<path d="M21.6 10.6v9.7a.7.7 0 0 1-.6.6h-8a.7.7 0 0 1-.6-.6v-1.8c0-2.2.3-4.4.8-5.3a2 2 0 0 1 1.3-1c1-.4 2.9-.2 3.7-.2 0 0 2.3 0 2.3-1.3 0-1-1-1-1-1-1.2 0-2 0-2.6-.2-1-.4-1-1.1-1-1.3 0-2.7-4-3-7.5-2.4-3.9.7 0 6.2 0 13.5v1a.7.7 0 0 1-.7.6H3.8a.7.7 0 0 1-.6-.6V3.5a.7.7 0 0 1 .6-.6h3.7a.7.7 0 0 1 .7.6c0 .6.6.9 1 .6 1.3-1 3-1.5 5-1.5 4.2 0 7.4 2.5 7.4 8zm-7-2a1.4 1.4 0 1 0-2.9 0 1.4 1.4 0 0 0 2.9 0z"/>',
 };
 
 export const Icons = {

package/integrations/asides.ts

@@ -107,10 +107,10 @@ function transformUnhandledDirective(
  * ```astro
  * <aside class="starlight-aside starlight-aside--tip" aria-label="Did you know?">
  *   <p class="starlight-aside__title" aria-hidden="true">Did you know?</p>
- *   <section class="starlight-aside__content">
+ *   <div class="starlight-aside__content">
  *     <p>Astro helps you build faster websites with “Islands Architecture”.</p>
- *   </section>
- * </Aside>
+ *   </div>
+ * </aside>
  * ```
  */
 function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
@@ -204,7 +204,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 						),
 						...titleNode,
 					]),
-					h('section', { class: 'starlight-aside__content' }, node.children),
+					h('div', { class: 'starlight-aside__content' }, node.children),
 				]
 			);
 

package/integrations/expressive-code/index.ts

@@ -8,6 +8,7 @@ import type { AstroIntegration } from 'astro';
 import type { StarlightConfig } from '../../types';
 import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { pathToLocale } from '../shared/pathToLocale';
+import { slugToLocale } from '../shared/slugToLocale';
 import {
 	applyStarlightUiThemeColors,
 	preprocessThemes,
@@ -152,7 +153,10 @@ export function getStarlightEcConfigPreprocessor({
 				},
 				...otherStyleOverrides,
 			},
-			getBlockLocale: ({ file }) => pathToLocale(file.path, { starlightConfig, astroConfig }),
+			getBlockLocale: ({ file }) =>
+				file.url
+					? slugToLocale(file.url.pathname.slice(1), starlightConfig)
+					: pathToLocale(file.path, { starlightConfig, astroConfig }),
 			plugins,
 			...rest,
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.28.6",
+  "version": "0.29.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -170,14 +170,14 @@
     "astro": "^4.14.0"
   },
   "devDependencies": {
-    "@astrojs/markdown-remark": "^5.1.0",
+    "@astrojs/markdown-remark": "^5.3.0",
     "@playwright/test": "^1.45.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^18.16.19",
     "@vitest/coverage-v8": "^1.6.0",
-    "astro": "^4.15.3",
-    "vitest": "^1.6.0",
-    "linkedom": "^0.18.4"
+    "astro": "^4.16.10",
+    "linkedom": "^0.18.4",
+    "vitest": "^1.6.0"
   },
   "dependencies": {
     "@astrojs/mdx": "^3.1.3",
@@ -185,7 +185,7 @@
     "@pagefind/default-ui": "^1.0.3",
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
-    "astro-expressive-code": "^0.35.6",
+    "astro-expressive-code": "^0.38.3",
     "bcp-47": "^2.1.0",
     "hast-util-from-html": "^2.0.1",
     "hast-util-select": "^6.0.2",

package/schemas/social.ts

@@ -35,6 +35,7 @@ export const socialLinks = [
 	'zulip',
 	'pinterest',
 	'tiktok',
+	'nostr',
 ] as const;
 
 export const SocialLinksSchema = () =>
@@ -85,6 +86,7 @@ export const SocialLinksSchema = () =>
 					zulip: 'Zulip',
 					pinterest: 'Pinterest',
 					tiktok: 'TikTok',
+					nostr: 'Nostr',
 				}[key];
 				labelledLinks[key] = { label, url };
 			}

package/user-components/Aside.astro

@@ -29,7 +29,7 @@ if (!title) {
 	<p class="starlight-aside__title" aria-hidden="true">
 		<Icon name={icons[type]} class="starlight-aside__icon" />{title}
 	</p>
-	<section class="starlight-aside__content">
+	<div class="starlight-aside__content">
 		<slot />
-	</section>
+	</div>
 </aside>

package/user-components/rehype-tabs.ts

@@ -47,7 +47,7 @@ const getIDs = () => {
 
 /**
  * Rehype processor to extract tab panel data and turn each
- * `<starlight-tab-item>` into a `<section>` with the necessary
+ * `<starlight-tab-item>` into a `<div>` with the necessary
  * attributes.
  */
 const tabsProcessor = rehype()
@@ -73,8 +73,8 @@ const tabsProcessor = rehype()
 				// Remove `<TabItem>` props
 				delete node.properties.dataLabel;
 				delete node.properties.dataIcon;
-				// Turn into `<section>` with required attributes
-				node.tagName = 'section';
+				// Turn into `<div>` with required attributes
+				node.tagName = 'div';
 				node.properties.id = ids.panelId;
 				node.properties['aria-labelledby'] = ids.tabId;
 				node.properties.role = 'tabpanel';

package/utils/i18n.ts

@@ -79,7 +79,7 @@ function getAstroI18nConfig(config: StarlightConfig): NonNullable<AstroConfig['i
 			? Object.entries(config.locales).map(([locale, localeConfig]) => {
 					return {
 						codes: [localeConfig?.lang ?? locale],
-						path: locale === 'root' ? localeConfig?.lang ?? BuiltInDefaultLocale.lang : locale,
+						path: locale === 'root' ? (localeConfig?.lang ?? BuiltInDefaultLocale.lang) : locale,
 					};
 				})
 			: [config.defaultLocale.lang],

package/utils/navigation.ts

@@ -20,6 +20,8 @@ import type { StarlightConfig } from './user-config';
 const DirKey = Symbol('DirKey');
 const SlugKey = Symbol('SlugKey');
 
+const neverPathFormatter = createPathFormatter({ trailingSlash: 'never' });
+
 export interface Link {
 	type: 'link';
 	label: string;
@@ -73,11 +75,11 @@ function configItemToEntry(
 	routes: Route[]
 ): SidebarEntry {
 	if ('link' in item) {
-		return linkFromSidebarLinkItem(item, locale, currentPathname);
+		return linkFromSidebarLinkItem(item, locale);
 	} else if ('autogenerate' in item) {
 		return groupFromAutogenerateConfig(item, locale, routes, currentPathname);
 	} else if ('slug' in item) {
-		return linkFromInternalSidebarLinkItem(item, locale, currentPathname);
+		return linkFromInternalSidebarLinkItem(item, locale);
 	} else {
 		const label = pickLang(item.translations, localeToLang(locale)) || item.label;
 		return {
@@ -121,11 +123,7 @@ function groupFromAutogenerateConfig(
 const isAbsolute = (link: string) => /^https?:\/\//.test(link);
 
 /** Create a link entry from a manual link item in user config. */
-function linkFromSidebarLinkItem(
-	item: SidebarLinkItem,
-	locale: string | undefined,
-	currentPathname: string
-) {
+function linkFromSidebarLinkItem(item: SidebarLinkItem, locale: string | undefined) {
 	let href = item.link;
 	if (!isAbsolute(href)) {
 		href = ensureLeadingSlash(href);
@@ -133,20 +131,13 @@ function linkFromSidebarLinkItem(
 		if (locale) href = '/' + locale + href;
 	}
 	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
-	return makeSidebarLink(
-		href,
-		label,
-		currentPathname,
-		getSidebarBadge(item.badge, locale, label),
-		item.attrs
-	);
+	return makeSidebarLink(href, label, getSidebarBadge(item.badge, locale, label), item.attrs);
 }
 
 /** Create a link entry from an automatic internal link item in user config. */
 function linkFromInternalSidebarLinkItem(
 	item: InternalSidebarLinkItem,
-	locale: string | undefined,
-	currentPathname: string
+	locale: string | undefined
 ) {
 	// Astro passes root `index.[md|mdx]` entries with a slug of `index`
 	const slug = item.slug === 'index' ? '' : item.slug;
@@ -169,50 +160,39 @@ function linkFromInternalSidebarLinkItem(
 	}
 	const label =
 		pickLang(item.translations, localeToLang(locale)) || item.label || entry.entry.data.title;
-	return makeSidebarLink(
-		entry.slug,
-		label,
-		currentPathname,
-		getSidebarBadge(item.badge, locale, label),
-		item.attrs
-	);
+	return makeSidebarLink(entry.slug, label, getSidebarBadge(item.badge, locale, label), item.attrs);
 }
 
 /** Process sidebar link options to create a link entry. */
 function makeSidebarLink(
 	href: string,
 	label: string,
-	currentPathname: string,
 	badge?: Badge,
 	attrs?: LinkHTMLAttributes
 ): Link {
 	if (!isAbsolute(href)) {
 		href = formatPath(href);
 	}
-	const isCurrent = pathsMatch(encodeURI(href), currentPathname);
-	return makeLink({ label, href, isCurrent, badge, attrs });
+	return makeLink({ label, href, badge, attrs });
 }
 
 /** Create a link entry */
 function makeLink({
-	isCurrent = false,
 	attrs = {},
 	badge = undefined,
 	...opts
 }: {
 	label: string;
 	href: string;
-	isCurrent?: boolean;
 	badge?: Badge | undefined;
 	attrs?: LinkHTMLAttributes | undefined;
 }): Link {
-	return { type: 'link', ...opts, badge, isCurrent, attrs };
+	return { type: 'link', ...opts, badge, isCurrent: false, attrs };
 }
 
 /** Test if two paths are equivalent even if formatted differently. */
 function pathsMatch(pathA: string, pathB: string) {
-	const format = createPathFormatter({ trailingSlash: 'never' });
-	return format(pathA) === format(pathB);
+	return neverPathFormatter(pathA) === neverPathFormatter(pathB);
 }
 
 /** Get the segments leading to a page. */
@@ -268,11 +248,10 @@ function treeify(routes: Route[], baseDir: string): Dir {
 }
 
 /** Create a link entry for a given content collection entry. */
-function linkFromRoute(route: Route, currentPathname: string): Link {
+function linkFromRoute(route: Route): Link {
 	return makeSidebarLink(
 		slugToPathname(route.slug),
 		route.entry.data.sidebar.label || route.entry.data.title,
-		currentPathname,
 		route.entry.data.sidebar.badge,
 		route.entry.data.sidebar.attrs
 	);
@@ -286,7 +265,7 @@ function getOrder(routeOrDir: Route | Dir): number {
 	return isDir(routeOrDir)
 		? Math.min(...Object.values(routeOrDir).flatMap(getOrder))
 		: // If no order value is found, set it to the largest number possible.
-			routeOrDir.entry.data.sidebar.order ?? Number.MAX_VALUE;
+			(routeOrDir.entry.data.sidebar.order ?? Number.MAX_VALUE);
 }
 
 /** Sort a directory’s entries by user-specified order or alphabetically if no order specified. */
@@ -333,7 +312,7 @@ function dirToItem(
 ): SidebarEntry {
 	return isDir(dirOrRoute)
 		? groupFromDir(dirOrRoute, fullPath, dirName, currentPathname, locale, collapsed)
-		: linkFromRoute(dirOrRoute, currentPathname);
+		: linkFromRoute(dirOrRoute);
 }
 
 /** Create a sidebar entry for a given content directory. */
@@ -348,9 +327,25 @@ function sidebarFromDir(
 	);
 }
 
+/**
+ * Intermediate sidebar represents sidebar entries generated from the user config for a specific
+ * locale and do not contain any information about the current page.
+ * These representations are cached per locale to avoid regenerating them for each page.
+ * When generating the final sidebar for a page, the intermediate sidebar is cloned and the current
+ * page is marked as such.
+ *
+ * @see getSidebarFromIntermediateSidebar
+ */
+const intermediateSidebars = new Map<string | undefined, SidebarEntry[]>();
+
 /** Get the sidebar for the current page using the global config. */
 export function getSidebar(pathname: string, locale: string | undefined): SidebarEntry[] {
-	return getSidebarFromConfig(config.sidebar, pathname, locale);
+	let intermediateSidebar = intermediateSidebars.get(locale);
+	if (!intermediateSidebar) {
+		intermediateSidebar = getSidebarFromConfig(config.sidebar, pathname, locale);
+		intermediateSidebars.set(locale, intermediateSidebar);
+	}
+	return getSidebarFromIntermediateSidebar(intermediateSidebar, pathname);
 }
 
 /** Get the sidebar for the current page using the specified sidebar config. */
@@ -368,6 +363,34 @@ export function getSidebarFromConfig(
 	}
 }
 
+/** Transform an intermediate sidebar into a sidebar for the current page. */
+function getSidebarFromIntermediateSidebar(
+	intermediateSidebar: SidebarEntry[],
+	pathname: string
+): SidebarEntry[] {
+	const sidebar = structuredClone(intermediateSidebar);
+	setIntermediateSidebarCurrentEntry(sidebar, pathname);
+	return sidebar;
+}
+
+/** Marks the current page as such in an intermediate sidebar. */
+function setIntermediateSidebarCurrentEntry(
+	intermediateSidebar: SidebarEntry[],
+	pathname: string
+): boolean {
+	for (const entry of intermediateSidebar) {
+		if (entry.type === 'link' && pathsMatch(encodeURI(entry.href), pathname)) {
+			entry.isCurrent = true;
+			return true;
+		}
+
+		if (entry.type === 'group' && setIntermediateSidebarCurrentEntry(entry.entries, pathname)) {
+			return true;
+		}
+	}
+	return false;
+}
+
 /** Generates a deterministic string based on the content of the passed sidebar. */
 export function getSidebarHash(sidebar: SidebarEntry[]): string {
 	let hash = 0;

package/utils/starlight-page.ts

@@ -12,7 +12,7 @@ import {
 } from './route-data';
 import type { StarlightDocsEntry } from './routing';
 import { slugToLocaleData, urlToSlug } from './slugs';
-import { getPrevNextLinks, getSidebarFromConfig } from './navigation';
+import { getPrevNextLinks, getSidebar, getSidebarFromConfig } from './navigation';
 import { docsSchema } from '../schema';
 import type { Prettify, RemoveIndexSignature } from './types';
 import { DeprecatedLabelsPropProxy } from './i18n';
@@ -115,11 +115,9 @@ export async function generateStarlightPageRouteData({
 	const pageFrontmatter = await getStarlightPageFrontmatter(frontmatter);
 	const id = `${stripLeadingAndTrailingSlashes(slug)}.md`;
 	const localeData = slugToLocaleData(slug);
-	const sidebar = getSidebarFromConfig(
-		props.sidebar ? validateSidebarProp(props.sidebar) : config.sidebar,
-		url.pathname,
-		localeData.locale
-	);
+	const sidebar = props.sidebar
+		? getSidebarFromConfig(validateSidebarProp(props.sidebar), url.pathname, localeData.locale)
+		: getSidebar(url.pathname, localeData.locale);
 	const headings = props.headings ?? [];
 	const pageDocsEntry: StarlightPageDocsEntry = {
 		id,