@astrojs/starlight 0.34.8 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @astrojs/starlight
 
+## 0.35.0
+
+### Minor Changes
+
+- [#2261](https://github.com/withastro/starlight/pull/2261) [`778b743`](https://github.com/withastro/starlight/commit/778b743cdb832551ed576c745728358d8bbf9d7a) Thanks [@shubham-padia](https://github.com/shubham-padia)! - Adds support for using any of Starlight’s built-in icons in asides.
+
+- [#3272](https://github.com/withastro/starlight/pull/3272) [`e7fe267`](https://github.com/withastro/starlight/commit/e7fe26720b7527c39e3aab42ea9fd0468f92167c) Thanks [@delucis](https://github.com/delucis)! - Adds a new `generateId` option to Starlight’s `docsLoader()`
+
+  This enables overriding the default sluggifier used to convert content filenames to URLs.
+
+- [#3276](https://github.com/withastro/starlight/pull/3276) [`3917b20`](https://github.com/withastro/starlight/commit/3917b206da26522f73bbe0c1120de9acae5972c5) Thanks [@delucis](https://github.com/delucis)! - Excludes banner content from search results
+
+  Previously, content set in [`banner`](https://starlight.astro.build/reference/frontmatter/#banner) in page frontmatter was indexed by Starlight’s default search provider Pagefind. This could cause unexpected search results, especially for sites setting a common banner content on multiple pages. Starlight’s default `Banner` component is now excluded from search indexing.
+
+  This change does not impact `Banner` overrides using custom components.
+
+- [#3266](https://github.com/withastro/starlight/pull/3266) [`1161af0`](https://github.com/withastro/starlight/commit/1161af0c2fe26485da6123f8fd7205c53b0e45e5) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for custom HTML attributes on autogenerated sidebar links using the [`autogenerate.attrs`](https://starlight.astro.build/guides/sidebar/#custom-html-attributes-for-autogenerated-links) option.
+
+- [#3274](https://github.com/withastro/starlight/pull/3274) [`80ccff7`](https://github.com/withastro/starlight/commit/80ccff7c542794e04a4d2abb17227a076fa57c5d) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes an issue where some Starlight remark and rehype plugins were transforming Markdown and MDX content in non-Starlight pages.
+
+  ⚠️ **BREAKING CHANGE:**
+
+  Previously, some of Starlight’s remark and rehype plugins, most notably the plugin transforming Starlight's custom Markdown syntax for [rendering asides](https://starlight.astro.build/guides/authoring-content/#asides), were applied to all Markdown and MDX content. This included content from [individual Markdown pages](https://docs.astro.build/en/guides/markdown-content/#individual-markdown-pages) and content from [content collections](https://docs.astro.build/en/guides/content-collections/) other than the `docs` collection used by Starlight.
+
+  This change restricts the application of Starlight’s remark and rehype plugins to only Markdown and MDX content loaded using Starlight's [`docsLoader()`](https://starlight.astro.build/reference/configuration/#docsloader). If you were relying on this behavior, please let us know about your use case in the dedicated `#starlight` channel in the [Astro Discord](https://astro.build/chat/) or by [opening an issue](https://github.com/withastro/starlight/issues/new?template=---01-bug-report.yml).
+
+### Patch Changes
+
+- [#3266](https://github.com/withastro/starlight/pull/3266) [`1161af0`](https://github.com/withastro/starlight/commit/1161af0c2fe26485da6123f8fd7205c53b0e45e5) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Ensures invalid sidebar group configurations using the `attrs` option are properly reported as a type error.
+
+  Previously, invalid sidebar group configurations using the `attrs` option were not reported as a type error but only surfaced at runtime. This change is only a type-level change and does not affect the runtime behavior of Starlight which does not support the `attrs` option for sidebar groups.
+
+- [#3274](https://github.com/withastro/starlight/pull/3274) [`80ccff7`](https://github.com/withastro/starlight/commit/80ccff7c542794e04a4d2abb17227a076fa57c5d) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Prevents Starlight remark and rehype plugins from transforming Markdown and MDX content when using the Astro [`renderMarkdown()`](https://docs.astro.build/en/reference/content-loader-reference/#rendermarkdown) content loader API.
+
 ## 0.34.8
 
 ### Patch Changes

package/components/Banner.astro

@@ -2,7 +2,7 @@
 const { banner } = Astro.locals.starlightRoute.entry.data;
 ---
 
-{banner && <div class="sl-banner" set:html={banner.content} />}
+{banner && <div class="sl-banner" data-pagefind-ignore set:html={banner.content} />}
 
 <style>
 	@layer starlight.core {

package/index.ts

@@ -129,7 +129,7 @@ export default function StarlightIntegration(
 							}),
 						],
 						rehypePlugins: [
-							rehypeRtlCodeSupport(),
+							rehypeRtlCodeSupport({ astroConfig: config }),
 							// Process headings and add anchor links.
 							...starlightAutolinkHeadings({
 								starlightConfig,

package/integrations/asides.ts

@@ -1,7 +1,7 @@
 /// <reference types="mdast-util-directive" />
 
 import type { AstroConfig, AstroIntegration, AstroUserConfig } from 'astro';
-import { h as _h, s as _s, type Properties } from 'hastscript';
+import { h as _h, s as _s, type Properties, type Result } from 'hastscript';
 import type { Node, Paragraph as P, Parent, PhrasingContent, Root } from 'mdast';
 import {
 	type Directives,
@@ -14,7 +14,12 @@ import { toString } from 'mdast-util-to-string';
 import remarkDirective from 'remark-directive';
 import type { Plugin, Transformer } from 'unified';
 import { visit } from 'unist-util-visit';
-import type { HookParameters, StarlightConfig } from '../types';
+import type { HookParameters, StarlightConfig, StarlightIcon } from '../types';
+import { getRemarkRehypeDocsCollectionPath, shouldTransformFile } from './remark-rehype-utils';
+import { Icons } from '../components/Icons';
+import { fromHtml } from 'hast-util-from-html';
+import type { Element } from 'hast';
+import { AstroError } from 'astro/errors';
 
 interface AsidesOptions {
 	starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales'>;
@@ -87,6 +92,20 @@ function transformUnhandledDirective(
 	}
 }
 
+/** Hacky function that generates the children of an mdast SVG tree. */
+function makeSvgChildNodes(children: Result['children']): any[] {
+	const nodes: P[] = [];
+	for (const child of children) {
+		if (child.type !== 'element') continue;
+		nodes.push({
+			type: 'paragraph',
+			data: { hName: child.tagName, hProperties: child.properties },
+			children: makeSvgChildNodes(child.children),
+		});
+	}
+	return nodes;
+}
+
 /**
  * remark plugin that converts blocks delimited with `:::` into styled
  * asides (a.k.a. “callouts”, “admonitions”, etc.). Depends on the
@@ -148,7 +167,11 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 		],
 	};
 
+	const docsCollectionPath = getRemarkRehypeDocsCollectionPath(options.astroConfig.srcDir);
+
 	const transformer: Transformer<Root> = (tree, file) => {
+		if (!shouldTransformFile(file, docsCollectionPath)) return;
+
 		const lang = options.absolutePathToLang(file.path);
 		const t = options.useTranslations(lang);
 		visit(tree, (node, index, parent) => {
@@ -159,6 +182,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 				return;
 			}
 			const variant = node.name;
+			const attributes = node.attributes;
 			if (!isAsideVariant(variant)) return;
 
 			// remark-directive converts a container’s “label” to a paragraph added as the head of its
@@ -180,6 +204,19 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 				node.children.splice(0, 1);
 			}
 
+			let iconPath = iconPaths[variant];
+
+			if (attributes?.['icon']) {
+				const iconName = attributes['icon'] as StarlightIcon;
+				const icon = Icons[iconName];
+				if (!icon) throwInvalidAsideIconError(iconName);
+				// Omit the root node and return only the first child which is the SVG element.
+				const iconHastTree = fromHtml(`<svg>${icon}</svg>`, { fragment: true, space: 'svg' })
+					.children[0] as Element;
+				// Render all SVG child nodes.
+				iconPath = makeSvgChildNodes(iconHastTree.children);
+			}
+
 			const aside = h(
 				'aside',
 				{
@@ -197,7 +234,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 								fill: 'currentColor',
 								class: 'starlight-aside__icon',
 							},
-							iconPaths[variant]
+							iconPath
 						),
 						...titleNode,
 					]),
@@ -216,6 +253,14 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 
 type RemarkPlugins = NonNullable<NonNullable<AstroUserConfig['markdown']>['remarkPlugins']>;
 
+export function throwInvalidAsideIconError(icon: string) {
+	throw new AstroError(
+		'Invalid aside icon',
+		`An aside custom icon must be set to the name of one of Starlight\’s built-in icons, but received \`${icon}\`.\n\n` +
+			'See https://starlight.astro.build/reference/icons/#all-icons for a list of available icons.'
+	);
+}
+
 export function starlightAsides(options: AsidesOptions): RemarkPlugins {
 	return [remarkDirective, remarkAsides(options)];
 }

package/integrations/code-rtl-support.ts

@@ -1,5 +1,12 @@
+import type { AstroConfig } from 'astro';
 import type { Root } from 'hast';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
+import type { VFile } from 'vfile';
+import { getRemarkRehypeDocsCollectionPath, shouldTransformFile } from './remark-rehype-utils';
+
+interface RtlCodeSupportOptions {
+	astroConfig: Pick<AstroConfig, 'srcDir'>;
+}
 
 /**
  * rehype plugin that adds `dir` attributes to `<code>` and `<pre>`
@@ -15,8 +22,12 @@ import { CONTINUE, SKIP, visit } from 'unist-util-visit';
  * - `<code>` is often LTR, but could also be RTL. `dir="auto"` ensures the bidirectional
  *   algorithm treats the contents of `<code>` in isolation and gives its best guess.
  */
-export function rehypeRtlCodeSupport() {
-	return () => (root: Root) => {
+export function rehypeRtlCodeSupport({ astroConfig }: RtlCodeSupportOptions) {
+	const docsCollectionPath = getRemarkRehypeDocsCollectionPath(astroConfig.srcDir);
+
+	return () => (root: Root, file: VFile) => {
+		if (!shouldTransformFile(file, docsCollectionPath)) return;
+
 		visit(root, 'element', (el) => {
 			if (el.tagName === 'pre' || el.tagName === 'code') {
 				el.properties ||= {};

package/integrations/heading-links.ts

@@ -6,7 +6,7 @@ import { h } from 'hastscript';
 import type { Transformer } from 'unified';
 import { SKIP, visit } from 'unist-util-visit';
 import type { HookParameters, StarlightConfig } from '../types';
-import { resolveCollectionPath } from '../utils/collection';
+import { getRemarkRehypeDocsCollectionPath, shouldTransformFile } from './remark-rehype-utils';
 
 const AnchorLinkIcon = h(
 	'span',
@@ -30,8 +30,7 @@ export default function rehypeAutolinkHeadings(
 	absolutePathToLang: AutolinkHeadingsOptions['absolutePathToLang']
 ) {
 	const transformer: Transformer<Root> = (tree, file) => {
-		// If the document is not part of the Starlight docs collection, skip it.
-		if (!normalizePath(file.path).startsWith(docsCollectionPath)) return;
+		if (!shouldTransformFile(file, docsCollectionPath)) return;
 
 		const pageLang = absolutePathToLang(file.path);
 		const t = useTranslationsForLang(pageLang);
@@ -93,23 +92,13 @@ export const starlightAutolinkHeadings = ({
 					{ experimentalHeadingIdCompat: astroConfig.experimental?.headingIdCompat },
 				],
 				rehypeAutolinkHeadings(
-					normalizePath(resolveCollectionPath('docs', astroConfig.srcDir)),
+					getRemarkRehypeDocsCollectionPath(astroConfig.srcDir),
 					useTranslations,
 					absolutePathToLang
 				),
 			]
 		: [];
 
-/**
- * File path separators seems to be inconsistent on Windows when the rehype plugin is used on
- * Markdown vs MDX files.
- * For the time being, we normalize the path to unix style path.
- */
-const backSlashRegex = /\\/g;
-function normalizePath(path: string) {
-	return path.replace(backSlashRegex, '/');
-}
-
 // This utility is inlined from https://github.com/syntax-tree/hast-util-heading-rank
 // Copyright (c) 2020 Titus Wormer <tituswormer@gmail.com>
 // MIT License: https://github.com/syntax-tree/hast-util-heading-rank/blob/main/license

package/integrations/remark-rehype-utils.ts

@@ -0,0 +1,38 @@
+import type { AstroConfig } from 'astro';
+import type { VFile } from 'vfile';
+import { resolveCollectionPath } from '../utils/collection';
+
+/**
+ * Returns the path to the Starlight docs collection ready to be used in remark/rehype plugins,
+ * e.g. with the `shouldTransformFile()` utility to determine if a file should be transformed
+ * by a plugin or not.
+ */
+export function getRemarkRehypeDocsCollectionPath(srcDir: AstroConfig['srcDir']) {
+	return normalizePath(resolveCollectionPath('docs', srcDir));
+}
+
+/**
+ * Determines if a file should be transformed by a remark/rehype plugin, e.g. files without a known
+ * path or files that are not part of the Starlight docs collection should be skipped.
+ */
+export function shouldTransformFile(file: VFile, docsCollectionPath: string) {
+	// If the content is rendered using the content loader `renderMarkdown()` API, a file path
+	// is not provided.
+	// In that case, we skip the file.
+	if (!file?.path) return false;
+
+	// If the document is not part of the Starlight docs collection, skip it.
+	if (!normalizePath(file.path).startsWith(docsCollectionPath)) return false;
+
+	return true;
+}
+
+/**
+ * File path separators seems to be inconsistent on Windows between remark/rehype plugins used on
+ * Markdown vs MDX files.
+ * For the time being, we normalize all paths to unix style paths.
+ */
+const backSlashRegex = /\\/g;
+function normalizePath(path: string) {
+	return path.replace(backSlashRegex, '/');
+}

package/loaders.ts

@@ -6,13 +6,30 @@ import { getCollectionPathFromRoot, type StarlightCollection } from './utils/col
 const docsExtensions = ['markdown', 'mdown', 'mkdn', 'mkd', 'mdwn', 'md', 'mdx'];
 const i18nExtensions = ['json', 'yml', 'yaml'];
 
-export function docsLoader(): Loader {
+type GlobOptions = Parameters<typeof glob>[0];
+type GenerateIdFunction = NonNullable<GlobOptions['generateId']>;
+
+/**
+ * Loads content files from the `src/content/docs/` directory, ignoring filenames starting with `_`.
+ */
+export function docsLoader({
+	generateId,
+}: {
+	/**
+	 * Function that generates an ID for an entry. Default implementation generates a slug from the entry path.
+	 * @returns The ID of the entry. Must be unique per collection.
+	 **/
+	generateId?: GenerateIdFunction;
+} = {}): Loader {
 	return {
 		name: 'starlight-docs-loader',
-		load: createGlobLoadFn('docs'),
+		load: createGlobLoadFn('docs', generateId),
 	};
 }
 
+/**
+ * Loads data files from the `src/content/i18n/` directory, ignoring filenames starting with `_`.
+ */
 export function i18nLoader(): Loader {
 	return {
 		name: 'starlight-i18n-loader',
@@ -20,7 +37,10 @@ export function i18nLoader(): Loader {
 	};
 }
 
-function createGlobLoadFn(collection: StarlightCollection): Loader['load'] {
+function createGlobLoadFn(
+	collection: StarlightCollection,
+	generateId?: GenerateIdFunction
+): Loader['load'] {
 	return (context: LoaderContext) => {
 		const extensions = collection === 'docs' ? docsExtensions : i18nExtensions;
 
@@ -32,9 +52,12 @@ function createGlobLoadFn(collection: StarlightCollection): Loader['load'] {
 			extensions.push('mdoc');
 		}
 
-		return glob({
+		const options: GlobOptions = {
 			base: getCollectionPathFromRoot(collection, context.config),
 			pattern: `**/[^_]*.{${extensions.join(',')}}`,
-		}).load(context);
+		};
+		if (generateId) options.generateId = generateId;
+
+		return glob(options).load(context);
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.34.8",
+  "version": "0.35.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",

package/schemas/sidebar.ts

@@ -14,6 +14,14 @@ const SidebarBaseSchema = z.object({
 });
 
 const SidebarGroupSchema = SidebarBaseSchema.extend({
+	/**
+	 * Explicitly prevent custom attributes on groups as the final type for supported sidebar item
+	 * is a non-discriminated union where TypeScript will not perform excess property checks.
+	 * This means that a user could define a sidebar group with custom attributes, not getting a
+	 * TypeScript error, and only have it fail at runtime.
+	 * @see https://github.com/microsoft/TypeScript/issues/20863
+	 */
+	attrs: z.never().optional(),
 	/** Whether this item should be collapsed by default. */
 	collapsed: z.boolean().default(false),
 });
@@ -22,7 +30,7 @@ const SidebarGroupSchema = SidebarBaseSchema.extend({
 // `Record<string, string | number | boolean | undefined>` but typed as `HTMLAttributes<'a'>`
 // for user convenience.
 const linkHTMLAttributesSchema = z.record(
-	z.union([z.string(), z.number(), z.boolean(), z.undefined()])
+	z.union([z.string(), z.number(), z.boolean(), z.undefined(), z.null()])
 ) as z.Schema<Omit<HTMLAttributes<'a'>, keyof AstroBuiltinAttributes | 'children'>>;
 export type LinkHTMLAttributes = z.infer<typeof linkHTMLAttributesSchema>;
 
@@ -46,6 +54,8 @@ const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
 		 * Defaults to the `AutoSidebarGroup` `collapsed` value.
 		 */
 		collapsed: z.boolean().optional(),
+		/** HTML attributes to add to the autogenerated link items. */
+		attrs: SidebarLinkItemHTMLAttributesSchema(),
 		// 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(),

package/user-components/Aside.astro

@@ -1,6 +1,8 @@
 ---
 import { AstroError } from 'astro/errors';
 import Icon from './Icon.astro';
+import { Icons, type StarlightIcon } from '../components/Icons';
+import { throwInvalidAsideIconError } from '../integrations/asides';
 
 const asideVariants = ['note', 'tip', 'caution', 'danger'] as const;
 const icons = { note: 'information', tip: 'rocket', caution: 'warning', danger: 'error' } as const;
@@ -8,9 +10,10 @@ const icons = { note: 'information', tip: 'rocket', caution: 'warning', danger:
 interface Props {
 	type?: (typeof asideVariants)[number];
 	title?: string;
+	icon?: StarlightIcon;
 }
 
-let { type = 'note', title } = Astro.props;
+let { type = 'note', title, icon } = Astro.props;
 
 if (!asideVariants.includes(type)) {
 	throw new AstroError(
@@ -20,6 +23,8 @@ if (!asideVariants.includes(type)) {
 	);
 }
 
+if (icon && !Icons[icon]) throwInvalidAsideIconError(icon);
+
 if (!title) {
 	title = Astro.locals.t(`aside.${type}`);
 }
@@ -27,7 +32,7 @@ if (!title) {
 
 <aside aria-label={title} class={`starlight-aside starlight-aside--${type}`}>
 	<p class="starlight-aside__title" aria-hidden="true">
-		<Icon name={icons[type]} class="starlight-aside__icon" />{title}
+		<Icon name={icon || icons[type]} class="starlight-aside__icon" />{title}
 	</p>
 	<div class="starlight-aside__content">
 		<slot />

package/utils/navigation.ts

@@ -96,7 +96,7 @@ function groupFromAutogenerateConfig(
 	routes: Route[],
 	currentPathname: string
 ): SidebarGroup {
-	const { collapsed: subgroupCollapsed, directory } = item.autogenerate;
+	const { attrs, collapsed: subgroupCollapsed, directory } = item.autogenerate;
 	const localeDir = locale ? locale + '/' + directory : directory;
 	const dirDocs = routes.filter((doc) => {
 		const filePathFromContentDir = getRoutePathRelativeToCollectionRoot(doc, locale);
@@ -112,7 +112,13 @@ function groupFromAutogenerateConfig(
 	return {
 		type: 'group',
 		label,
-		entries: sidebarFromDir(tree, currentPathname, locale, subgroupCollapsed ?? item.collapsed),
+		entries: sidebarFromDir(
+			tree,
+			currentPathname,
+			locale,
+			subgroupCollapsed ?? item.collapsed,
+			attrs
+		),
 		collapsed: item.collapsed,
 		badge: getSidebarBadge(item.badge, locale, label),
 	};
@@ -268,12 +274,12 @@ function treeify(routes: Route[], locale: string | undefined, baseDir: string):
 }
 
 /** Create a link entry for a given content collection entry. */
-function linkFromRoute(route: Route): SidebarLink {
+function linkFromRoute(route: Route, attrs?: LinkHTMLAttributes): SidebarLink {
 	return makeSidebarLink(
 		slugToPathname(route.slug),
 		route.entry.data.sidebar.label || route.entry.data.title,
 		route.entry.data.sidebar.badge,
-		route.entry.data.sidebar.attrs
+		{ ...attrs, ...route.entry.data.sidebar.attrs }
 	);
 }
 
@@ -307,10 +313,11 @@ function groupFromDir(
 	dirName: string,
 	currentPathname: string,
 	locale: string | undefined,
-	collapsed: boolean
+	collapsed: boolean,
+	attrs?: LinkHTMLAttributes
 ): SidebarGroup {
 	const entries = sortDirEntries(Object.entries(dir)).map(([key, dirOrRoute]) =>
-		dirToItem(dirOrRoute, `${fullPath}/${key}`, key, currentPathname, locale, collapsed)
+		dirToItem(dirOrRoute, `${fullPath}/${key}`, key, currentPathname, locale, collapsed, attrs)
 	);
 	return {
 		type: 'group',
@@ -328,11 +335,12 @@ function dirToItem(
 	dirName: string,
 	currentPathname: string,
 	locale: string | undefined,
-	collapsed: boolean
+	collapsed: boolean,
+	attrs?: LinkHTMLAttributes
 ): SidebarEntry {
 	return isDir(dirOrRoute)
-		? groupFromDir(dirOrRoute, fullPath, dirName, currentPathname, locale, collapsed)
-		: linkFromRoute(dirOrRoute);
+		? groupFromDir(dirOrRoute, fullPath, dirName, currentPathname, locale, collapsed, attrs)
+		: linkFromRoute(dirOrRoute, attrs);
 }
 
 /** Create a sidebar entry for a given content directory. */
@@ -340,10 +348,11 @@ function sidebarFromDir(
 	tree: Dir,
 	currentPathname: string,
 	locale: string | undefined,
-	collapsed: boolean
+	collapsed: boolean,
+	attrs?: LinkHTMLAttributes
 ) {
 	return sortDirEntries(Object.entries(tree)).map(([key, dirOrRoute]) =>
-		dirToItem(dirOrRoute, key, key, currentPathname, locale, collapsed)
+		dirToItem(dirOrRoute, key, key, currentPathname, locale, collapsed, attrs)
 	);
 }