@astrojs/starlight 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @astrojs/starlight
 
+## 0.19.0
+
+### Minor Changes
+
+- [#1485](https://github.com/withastro/starlight/pull/1485) [`2cb3578`](https://github.com/withastro/starlight/commit/2cb35782dace67c7c418a31005419fa95493b3d3) Thanks [@timokoessler](https://github.com/timokoessler)! - Add support for setting html attributes of hero action links
+
+- [#1175](https://github.com/withastro/starlight/pull/1175) [`dd11b95`](https://github.com/withastro/starlight/commit/dd11b9538abdf4b5ba2ef70e07c0edda03e95add) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds a new `<StarlightPage>` component to use the Starlight layout in custom pages.
+
+  To learn more about this new feature, check out the new [“Using Starlight’s design in custom pages” guide](https://starlight.astro.build/guides/pages/#using-starlights-design-in-custom-pages).
+
+- [#1499](https://github.com/withastro/starlight/pull/1499) [`97bf523`](https://github.com/withastro/starlight/commit/97bf523923fb9678c12f58fcdbe36757f0e56ceb) Thanks [@delucis](https://github.com/delucis)! - Adds a new `<Aside>` component
+
+  The new component is in addition to the existing custom Markdown syntax.
+
 ## 0.18.1
 
 ### Patch Changes

package/components/CallToAction.astro

@@ -1,4 +1,5 @@
 ---
+import type { HTMLAttributes } from 'astro/types';
 import Icon from '../user-components/Icon.astro';
 import type { Icons } from './Icons';
 
@@ -6,12 +7,14 @@ interface Props {
 	variant: 'primary' | 'secondary' | 'minimal';
 	link: string;
 	icon?: undefined | { type: 'icon'; name: keyof typeof Icons } | { type: 'raw'; html: string };
+	attrs?: Omit<HTMLAttributes<'a'>, 'href'>;
 }
 
 const { link, variant, icon } = Astro.props;
+const { class: customClass, ...attrs } = Astro.props.attrs || {};
 ---
 
-<a class:list={['sl-flex action', variant]} href={link}>
+<a class:list={['sl-flex action', variant, customClass]} href={link} {...attrs}>
 	<slot />
 	{icon?.type === 'icon' && <Icon name={icon.name} size="1.5rem" />}
 	{icon?.type === 'raw' && <Fragment set:html={icon.html} />}

package/components/StarlightPage.astro

@@ -0,0 +1,13 @@
+---
+import {
+	generateStarlightPageRouteData,
+	type StarlightPageProps as Props,
+} from '../utils/starlight-page';
+import Page from './Page.astro';
+
+export type StarlightPageProps = Props;
+---
+
+<Page {...await generateStarlightPageRouteData({ props: Astro.props, url: Astro.url })}>
+	<slot />
+</Page>

package/components.ts

@@ -1,3 +1,4 @@
+export { default as Aside } from './user-components/Aside.astro';
 export { default as Card } from './user-components/Card.astro';
 export { default as CardGrid } from './user-components/CardGrid.astro';
 export { default as Icon } from './user-components/Icon.astro';

package/integrations/virtual-user-config.ts

@@ -48,6 +48,11 @@ export function vitePluginStarlightUserConfig(
 						opts.logo.light
 				  )}; export const logos = { dark, light };`
 			: 'export const logos = {};',
+		'virtual:starlight/collection-config': `let userCollections;
+			try {
+				userCollections = (await import('/src/content/config.ts')).collections;
+			} catch {}
+			export const collections = userCollections;`,
 		...virtualComponentModules,
 	} satisfies Record<string, string>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -98,6 +98,10 @@
       "types": "./components/Page.astro.tsx",
       "import": "./components/Page.astro"
     },
+    "./components/StarlightPage.astro": {
+      "types": "./components/StarlightPage.astro.tsx",
+      "import": "./components/StarlightPage.astro"
+    },
     "./components/Footer.astro": {
       "types": "./components/Footer.astro.tsx",
       "import": "./components/Footer.astro"
@@ -169,7 +173,7 @@
     "@astrojs/markdown-remark": "^4.2.1",
     "@types/node": "^18.16.19",
     "@vitest/coverage-v8": "^1.2.2",
-    "astro": "^4.3.4",
+    "astro": "^4.3.5",
     "vitest": "^1.2.2"
   },
   "dependencies": {

package/schemas/hero.ts

@@ -64,6 +64,8 @@ export const HeroSchema = ({ image }: SchemaContext) =>
 							: ({ type: 'raw', html: icon } as const);
 					})
 					.optional(),
+				/** HTML attributes to add to the link */
+				attrs: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(),
 			})
 			.array()
 			.default([]),

package/user-components/Aside.astro

@@ -0,0 +1,38 @@
+---
+import { AstroError } from 'astro/errors';
+import { slugToLocaleData, urlToSlug } from '../utils/slugs';
+import { useTranslations } from '../utils/translations';
+import Icon from './Icon.astro';
+
+const asideVariants = ['note', 'tip', 'caution', 'danger'] as const;
+const icons = { note: 'information', tip: 'rocket', caution: 'warning', danger: 'error' } as const;
+
+interface Props {
+	type?: (typeof asideVariants)[number];
+	title?: string;
+}
+
+let { type = 'note', title } = Astro.props;
+
+if (!asideVariants.includes(type)) {
+	throw new AstroError(
+		'Invalid `type` prop passed to the `<Aside>` component.\n',
+		`Received: ${JSON.stringify(type)}\n` +
+			`Expected one of ${asideVariants.map((i) => JSON.stringify(i)).join(', ')}`
+	);
+}
+
+if (!title) {
+	const { locale } = slugToLocaleData(urlToSlug(Astro.url));
+	title = useTranslations(locale)(`aside.${type}`);
+}
+---
+
+<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}
+	</p>
+	<section class="starlight-aside__content">
+		<slot />
+	</section>
+</aside>

package/utils/error-map.ts

@@ -11,6 +11,10 @@ type TypeOrLiteralErrByPathEntry = {
 	expected: unknown[];
 };
 
+export function throwValidationError(error: z.ZodError, message: string): never {
+	throw new Error(`${message}\n${error.issues.map((i) => i.message).join('\n')}`);
+}
+
 export const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 	const baseErrorPath = flattenErrorPath(baseError.path);
 	if (baseError.code === 'invalid_union') {

package/utils/plugins.ts

@@ -1,7 +1,7 @@
 import type { AstroIntegration } from 'astro';
 import { z } from 'astro/zod';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../utils/user-config';
-import { errorMap } from '../utils/error-map';
+import { errorMap, throwValidationError } from '../utils/error-map';
 
 /**
  * Runs Starlight plugins in the order that they are configured after validating the user-provided
@@ -82,10 +82,6 @@ export async function runPlugins(
 	return { integrations, starlightConfig: starlightConfig.data };
 }
 
-function throwValidationError(error: z.ZodError, message: string): never {
-	throw new Error(`${message}\n${error.issues.map((i) => i.message).join('\n')}`);
-}
-
 // https://github.com/withastro/astro/blob/910eb00fe0b70ca80bd09520ae100e8c78b675b5/packages/astro/src/core/config/schema.ts#L113
 const astroIntegrationSchema = z.object({
 	name: z.string(),

package/utils/route-data.ts

@@ -10,7 +10,7 @@ import type { Route } from './routing';
 import { localizedId } from './slugs';
 import { useTranslations } from './translations';
 
-interface PageProps extends Route {
+export interface PageProps extends Route {
 	headings: MarkdownHeading[];
 }
 
@@ -54,7 +54,7 @@ export function generateRouteData({
 	};
 }
 
-function getToC({ entry, locale, headings }: PageProps) {
+export function getToC({ entry, locale, headings }: PageProps) {
 	const tocConfig =
 		entry.data.template === 'splash'
 			? false

package/utils/slugs.ts

@@ -101,3 +101,21 @@ export function localizedId(id: string, locale: string | undefined): string {
 		return id;
 	}
 }
+
+/** Extract the slug from a URL. */
+export function urlToSlug(url: URL): string {
+	let pathname = url.pathname;
+	const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+	if (pathname.startsWith(base)) pathname = pathname.replace(base, '');
+	const segments = pathname.split('/');
+	const htmlExt = '.html';
+	if (segments.at(-1) === 'index.html') {
+		// Remove trailing `index.html`.
+		segments.pop();
+	} else if (segments.at(-1)?.endsWith(htmlExt)) {
+		// Remove trailing `.html`.
+		const last = segments.pop();
+		if (last) segments.push(last.slice(0, -1 * htmlExt.length));
+	}
+	return segments.filter(Boolean).join('/');
+}

package/utils/starlight-page.ts

@@ -0,0 +1,209 @@
+import { z } from 'astro/zod';
+import { type ContentConfig, type SchemaContext } from 'astro:content';
+import config from 'virtual:starlight/user-config';
+import { errorMap, throwValidationError } from './error-map';
+import { stripLeadingAndTrailingSlashes } from './path';
+import { getToC, type PageProps, type StarlightRouteData } from './route-data';
+import type { StarlightDocsEntry } from './routing';
+import { slugToLocaleData, urlToSlug } from './slugs';
+import { getPrevNextLinks, getSidebar } from './navigation';
+import { useTranslations } from './translations';
+import { docsSchema } from '../schema';
+
+/**
+ * The frontmatter schema for Starlight pages derived from the default schema for Starlight’s
+ * `docs` content collection.
+ * The frontmatter schema for Starlight pages cannot include some properties which will be omitted
+ * and some others needs to be refined to a stricter type.
+ */
+const StarlightPageFrontmatterSchema = async (context: SchemaContext) => {
+	const userDocsSchema = await getUserDocsSchema();
+	const schema = typeof userDocsSchema === 'function' ? userDocsSchema(context) : userDocsSchema;
+
+	return schema.transform((frontmatter) => {
+		/**
+		 * Starlight pages can only be edited if an edit URL is explicitly provided.
+		 * The `sidebar` frontmatter prop only works for pages in an autogenerated links group.
+		 * Starlight pages edit links cannot be autogenerated.
+		 *
+		 * These changes to the schema are done using a transformer and not using the usual `omit`
+		 * method because when the frontmatter schema is extended by the user, an intersection between
+		 * the default schema and the user schema is created using the `and` method. Intersections in
+		 * Zod returns a `ZodIntersection` object which does not have some methods like `omit` or
+		 * `pick`.
+		 *
+		 * This transformer only sets the `editUrl` default value and removes the `sidebar` property
+		 * from the validated output but does not appply any changes to the input schema type itself so
+		 * this needs to be done manually.
+		 *
+		 * @see StarlightPageFrontmatter
+		 * @see https://github.com/colinhacks/zod#intersections
+		 */
+		const { editUrl, sidebar, ...others } = frontmatter;
+		const pageEditUrl = editUrl === undefined || editUrl === true ? false : editUrl;
+		return { ...others, editUrl: pageEditUrl };
+	});
+};
+
+/**
+ * Type of Starlight pages frontmatter schema.
+ * We manually refines the `editUrl` type and omit the `sidebar` property as it's not possible to
+ * do that on the schema itself using Zod but the proper validation is still using a transformer.
+ * @see StarlightPageFrontmatterSchema
+ */
+type StarlightPageFrontmatter = Omit<
+	z.input<Awaited<ReturnType<typeof StarlightPageFrontmatterSchema>>>,
+	'editUrl' | 'sidebar'
+> & { editUrl?: string | false };
+
+/**
+ * The props accepted by the `<StarlightPage/>` component.
+ */
+export type StarlightPageProps = Prettify<
+	// Remove the index signature from `Route`, omit undesired properties and make the rest optional.
+	Partial<Omit<RemoveIndexSignature<PageProps>, 'entry' | 'entryMeta' | 'id' | 'locale' | 'slug'>> &
+		// Add the sidebar definitions for a Starlight page.
+		Partial<Pick<StarlightRouteData, 'hasSidebar' | 'sidebar'>> & {
+			// And finally add the Starlight page frontmatter properties in a `frontmatter` property.
+			frontmatter: StarlightPageFrontmatter;
+		}
+>;
+
+/**
+ * A docs entry used for Starlight pages meant to be rendered by plugins and which is safe to cast
+ * to a `StarlightDocsEntry`.
+ * A Starlight page docs entry cannot be rendered like a content collection entry.
+ */
+type StarlightPageDocsEntry = Omit<StarlightDocsEntry, 'id' | 'render'> & {
+	/**
+	 * The unique ID for this Starlight page which cannot be inferred from codegen like content
+	 * collection entries.
+	 */
+	id: string;
+};
+
+export async function generateStarlightPageRouteData({
+	props,
+	url,
+}: {
+	props: StarlightPageProps;
+	url: URL;
+}): Promise<StarlightRouteData> {
+	const { isFallback, frontmatter, ...routeProps } = props;
+	const slug = urlToSlug(url);
+	const pageFrontmatter = await getStarlightPageFrontmatter(frontmatter);
+	const id = `${stripLeadingAndTrailingSlashes(slug)}.md`;
+	const localeData = slugToLocaleData(slug);
+	const sidebar = props.sidebar ?? getSidebar(url.pathname, localeData.locale);
+	const headings = props.headings ?? [];
+	const pageDocsEntry: StarlightPageDocsEntry = {
+		id,
+		slug,
+		body: '',
+		collection: 'docs',
+		data: {
+			...pageFrontmatter,
+			sidebar: {
+				attrs: {},
+				hidden: false,
+			},
+		},
+	};
+	const entry = pageDocsEntry as StarlightDocsEntry;
+	const entryMeta: StarlightRouteData['entryMeta'] = {
+		dir: props.dir ?? localeData.dir,
+		lang: props.lang ?? localeData.lang,
+		locale: localeData.locale,
+	};
+	const editUrl = pageFrontmatter.editUrl ? new URL(pageFrontmatter.editUrl) : undefined;
+	const lastUpdated =
+		pageFrontmatter.lastUpdated instanceof Date ? pageFrontmatter.lastUpdated : undefined;
+	const routeData: StarlightRouteData = {
+		...routeProps,
+		...localeData,
+		id,
+		editUrl,
+		entry,
+		entryMeta,
+		hasSidebar: props.hasSidebar ?? entry.data.template !== 'splash',
+		headings,
+		labels: useTranslations(localeData.locale).all(),
+		lastUpdated,
+		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
+		sidebar,
+		slug,
+		toc: getToC({
+			...routeProps,
+			...localeData,
+			entry,
+			entryMeta,
+			headings,
+			id,
+			locale: localeData.locale,
+			slug,
+		}),
+	};
+	if (isFallback) {
+		routeData.isFallback = true;
+	}
+	return routeData;
+}
+
+/** Validates the Starlight page frontmatter properties from the props received by a Starlight page. */
+async function getStarlightPageFrontmatter(frontmatter: StarlightPageFrontmatter) {
+	// This needs to be in sync with ImageMetadata.
+	// https://github.com/withastro/astro/blob/cf993bc263b58502096f00d383266cd179f331af/packages/astro/src/assets/types.ts#L32
+	const schema = await StarlightPageFrontmatterSchema({
+		image: () =>
+			z.object({
+				src: z.string(),
+				width: z.number(),
+				height: z.number(),
+				format: z.union([
+					z.literal('png'),
+					z.literal('jpg'),
+					z.literal('jpeg'),
+					z.literal('tiff'),
+					z.literal('webp'),
+					z.literal('gif'),
+					z.literal('svg'),
+					z.literal('avif'),
+				]),
+			}),
+	});
+
+	const pageFrontmatter = schema.safeParse(frontmatter, { errorMap });
+
+	if (!pageFrontmatter.success) {
+		throwValidationError(
+			pageFrontmatter.error,
+			'Invalid frontmatter props passed to the `<StarlightPage/>` component.'
+		);
+	}
+
+	return pageFrontmatter.data;
+}
+
+/** Returns the user docs schema and falls back to the default schema if needed. */
+async function getUserDocsSchema(): Promise<
+	NonNullable<ContentConfig['collections']['docs']['schema']>
+> {
+	const userCollections = (await import('virtual:starlight/collection-config')).collections;
+	return userCollections?.docs.schema ?? docsSchema();
+}
+
+// https://stackoverflow.com/a/66252656/1945960
+type RemoveIndexSignature<T> = {
+	[K in keyof T as string extends K
+		? never
+		: number extends K
+		? never
+		: symbol extends K
+		? never
+		: K]: T[K];
+};
+
+// https://www.totaltypescript.com/concepts/the-prettify-helper
+type Prettify<T> = {
+	[K in keyof T]: T[K];
+} & {};

package/virtual.d.ts

@@ -24,6 +24,10 @@ declare module 'virtual:starlight/user-images' {
 	};
 }
 
+declare module 'virtual:starlight/collection-config' {
+	export const collections: import('astro:content').ContentConfig['collections'] | undefined;
+}
+
 declare module 'virtual:starlight/components/Banner' {
 	const Banner: typeof import('./components/Banner.astro').default;
 	export default Banner;