@astrojs/starlight 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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
+
+- [#1487](https://github.com/withastro/starlight/pull/1487) [`6a72bda`](https://github.com/withastro/starlight/commit/6a72bda8c5569e2eda68fdf258ae9b1dc8b320d6) Thanks [@NavyStack](https://github.com/NavyStack)! - Improves Korean UI translations
+
+- [#1489](https://github.com/withastro/starlight/pull/1489) [`b0d36de`](https://github.com/withastro/starlight/commit/b0d36de3398d4895603a787b612b1f0747defbdc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes a potential text rendering issue with text containing colons.
+
 ## 0.18.0
 
 ### Minor 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/asides.ts

@@ -2,7 +2,14 @@
 
 import type { AstroConfig, AstroUserConfig } from 'astro';
 import { h as _h, s as _s, type Properties } from 'hastscript';
-import type { Paragraph as P, Root } from 'mdast';
+import type { Node, Paragraph as P, Parent, Root } from 'mdast';
+import {
+	type Directives,
+	directiveToMarkdown,
+	type TextDirective,
+	type LeafDirective,
+} from 'mdast-util-directive';
+import { toMarkdown } from 'mdast-util-to-markdown';
 import remarkDirective from 'remark-directive';
 import type { Plugin, Transformer } from 'unified';
 import { remove } from 'unist-util-remove';
@@ -37,6 +44,40 @@ function s(el: string, attrs: Properties = {}, children: any[] = []): P {
 	};
 }
 
+/** Checks if a node is a directive. */
+function isNodeDirective(node: Node): node is Directives {
+	return (
+		node.type === 'textDirective' ||
+		node.type === 'leafDirective' ||
+		node.type === 'containerDirective'
+	);
+}
+
+/**
+ * Transforms back directives not handled by Starlight to avoid breaking user content.
+ * For example, a user might write `x:y` in the middle of a sentence, where `:y` would be
+ * identified as a text directive, which are not used by Starlight, and we definitely want that
+ * text to be rendered verbatim in the output.
+ */
+function transformUnhandledDirective(
+	node: TextDirective | LeafDirective,
+	index: number,
+	parent: Parent
+) {
+	const textNode = {
+		type: 'text',
+		value: toMarkdown(node, { extensions: [directiveToMarkdown()] }),
+	} as const;
+	if (node.type === 'textDirective') {
+		parent.children[index] = textNode;
+	} else {
+		parent.children[index] = {
+			type: 'paragraph',
+			children: [textNode],
+		};
+	}
+}
+
 /**
  * remark plugin that converts blocks delimited with `:::` into styled
  * asides (a.k.a. “callouts”, “admonitions”, etc.). Depends on the
@@ -102,7 +143,11 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 		const locale = pathToLocale(file.history[0], options);
 		const t = options.useTranslations(locale);
 		visit(tree, (node, index, parent) => {
-			if (!parent || index === undefined || node.type !== 'containerDirective') {
+			if (!parent || index === undefined || !isNodeDirective(node)) {
+				return;
+			}
+			if (node.type === 'textDirective' || node.type === 'leafDirective') {
+				transformUnhandledDirective(node, index, parent);
 				return;
 			}
 			const variant = node.name;

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.0",
+  "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": {
@@ -183,6 +187,7 @@
     "hast-util-select": "^6.0.2",
     "hastscript": "^8.0.0",
     "mdast-util-directive": "^3.0.0",
+    "mdast-util-to-markdown": "^2.1.0",
     "pagefind": "^1.0.3",
     "rehype": "^13.0.1",
     "remark-directive": "^3.0.0",

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/translations/ko.json

@@ -1,24 +1,24 @@
 {
-  "skipLink.label": "컨텐츠로 이동",
+  "skipLink.label": "컨텐츠로 건너뛰기",
   "search.label": "검색",
-  "search.shortcutLabel": "(검색을 위해 / 키를 누르세요)",
+  "search.shortcutLabel": "(검색하려면 / 를 누르세요)",
   "search.cancelLabel": "취소",
-  "search.devWarning": "검색 기능은 프로덕션 환경에서만 사용할 수 있습니다.\n사이트를 로컬 환경에서 테스트하기 위해 빌드하고 미리보기(Preview) 하세요.",
+  "search.devWarning": "검색 기능은 운영 환경에서만 사용할 수 있습니다. \n로컬에서 테스트하려면 사이트를 빌드하고 미리보기를 해보세요.",
   "themeSelect.accessibleLabel": "테마 선택",
-  "themeSelect.dark": "어두움",
-  "themeSelect.light": "밝음",
+  "themeSelect.dark": "다크",
+  "themeSelect.light": "라이트",
   "themeSelect.auto": "자동",
   "languageSelect.accessibleLabel": "언어 선택",
   "menuButton.accessibleLabel": "메뉴",
   "sidebarNav.accessibleLabel": "메인",
-  "tableOfContents.onThisPage": "목차",
+  "tableOfContents.onThisPage": "이 페이지에서는",
   "tableOfContents.overview": "개요",
-  "i18n.untranslatedContent": "이 컨텐츠는 아직 번역되지 않았습니다.",
+  "i18n.untranslatedContent": "이 내용은 아직 번역본이 없습니다.",
   "page.editLink": "페이지 수정",
-  "page.lastUpdated": "최종 수정:",
-  "page.previousLink": "이전 페이지",
-  "page.nextLink": "다음 페이지",
-  "404.text": "페이지를 찾을 수 없습니다. URL을 확인하거나 검색창을 사용해보세요.",
+  "page.lastUpdated": "마지막 업데이트:",
+  "page.previousLink": "이전",
+  "page.nextLink": "다음",
+  "404.text": "페이지를 찾을 수 없습니다. URL을 확인하거나 검색 막대를 사용해 보세요.",
   "aside.note": "노트",
   "aside.tip": "팁",
   "aside.caution": "주의",

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;