@astrojs/starlight 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @astrojs/starlight
 
+## 0.13.0
+
+### Minor Changes
+
+- [#1023](https://github.com/withastro/starlight/pull/1023) [`a3b80f7`](https://github.com/withastro/starlight/commit/a3b80f71037504f2b8d7f1a641924215091122bb) Thanks [@kevinzunigacuellar](https://github.com/kevinzunigacuellar)! - Respect the `trailingSlash` and `build.format` Astro options when creating Starlight navigation links.
+
+  ⚠️ **Potentially breaking change:**
+  This change will cause small changes in link formatting for most sites.
+  These are unlikely to break anything, but if you care about link formatting, you may want to change some Astro settings.
+
+  If you want to preserve Starlight’s previous behavior, set `trailingSlash: 'always'` in your `astro.config.mjs`:
+
+  ```js
+  import { defineConfig } from 'astro/config';
+  import starlight from '@astrojs/starlight';
+
+  export default defineConfig({
+  	trailingSlash: 'always',
+  	integrations: [
+  		starlight({
+  			// ...
+  		}),
+  	],
+  });
+  ```
+
+- [#742](https://github.com/withastro/starlight/pull/742) [`c6a4bcb`](https://github.com/withastro/starlight/commit/c6a4bcb7982c54c513f20c96a9b2aaf9ac09094b) Thanks [@hippotastic](https://github.com/hippotastic)! - Adds Expressive Code as Starlight’s default code block renderer
+
+  ⚠️ **Potentially breaking change:**
+  This addition changes how Markdown code blocks are rendered. By default, Starlight will now use [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code).
+  If you were already customizing how code blocks are rendered and don't want to use the [features provided by Expressive Code](https://starlight.astro.build/guides/authoring-content/#expressive-code-features), you can preserve the previous behavior by setting the new config option `expressiveCode` to `false`.
+
+  If you had previously added Expressive Code manually to your Starlight project, you can now remove the manual set-up in `astro.config.mjs`:
+
+  - Move your configuration to Starlight’s new `expressiveCode` option.
+  - Remove the `astro-expressive-code` integration.
+
+  For example:
+
+  ```diff
+  import starlight from '@astrojs/starlight';
+  import { defineConfig } from 'astro/config';
+  - import expressiveCode from 'astro-expressive-code';
+
+  export default defineConfig({
+    integrations: [
+  -   expressiveCode({
+  -     themes: ['rose-pine'],
+  -   }),
+      starlight({
+        title: 'My docs',
+  +     expressiveCode: {
+  +       themes: ['rose-pine'],
+  +     },
+      }),
+    ],
+  });
+  ```
+
+  Note that the built-in Starlight version of Expressive Code sets some opinionated defaults that are different from the `astro-expressive-code` defaults. You may need to set some `styleOverrides` if you wish to keep styles exactly the same.
+
+- [#517](https://github.com/withastro/starlight/pull/517) [`5b549cb`](https://github.com/withastro/starlight/commit/5b549cb634f51d28bf9a7f92ad0d82c1671e788a) Thanks [@liruifengv](https://github.com/liruifengv)! - Add i18n support for default aside labels
+
+### Patch Changes
+
+- [#1088](https://github.com/withastro/starlight/pull/1088) [`4fe5537`](https://github.com/withastro/starlight/commit/4fe553749a6708fdb119b12a2dbc6b10a980bde1) Thanks [@Lootjs](https://github.com/Lootjs)! - i18n(ru): added Russian aside labels translation
+
+- [#1083](https://github.com/withastro/starlight/pull/1083) [`e03a653`](https://github.com/withastro/starlight/commit/e03a65313365b7dbe6095727b28b4e639c446f68) Thanks [@at-the-vr](https://github.com/at-the-vr)! - i18n(hi): Add Hindi language support
+
+- [#1075](https://github.com/withastro/starlight/pull/1075) [`2f2adf2`](https://github.com/withastro/starlight/commit/2f2adf29f2a13d5ff0f1577207210745a5ae7405) Thanks [@russbiggs](https://github.com/russbiggs)! - Add Slack social link icon
+
+- [#1065](https://github.com/withastro/starlight/pull/1065) [`2d72ed6`](https://github.com/withastro/starlight/commit/2d72ed67c666b26eae44649e70aecef3db815d19) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Ignore search keyboard shortcuts for elements with contents that are editable
+
+- [#1081](https://github.com/withastro/starlight/pull/1081) [`f27f781`](https://github.com/withastro/starlight/commit/f27f781556d37e73d0b1d902de745b67f8e4f24d) Thanks [@farisphp](https://github.com/farisphp)! - i18n(id): Add Indonesian aside labels translation
+
+- [#1082](https://github.com/withastro/starlight/pull/1082) [`ce27486`](https://github.com/withastro/starlight/commit/ce27486fabd3884ed4bca9372ebd72a0597ab765) Thanks [@bogdaaamn](https://github.com/bogdaaamn)! - i18n(ro): Add Romanian UI translations
+
 ## 0.12.1
 
 ### Patch Changes

package/components/Icons.ts

@@ -99,4 +99,6 @@ export const Icons = {
 		'<path d="M14.41 16.87a3.38 3.38 0 0 1-2.37.63 3.37 3.37 0 0 1-2.36-.63 1 1 0 0 0-1.42 1.41 5.11 5.11 0 0 0 3.78 1.22 5.12 5.12 0 0 0 3.78-1.22 1 1 0 1 0-1.41-1.41ZM9.2 15a1 1 0 1 0-1-1 1 1 0 0 0 1 1Zm6-2a1 1 0 1 0 1 1 1 1 0 0 0-1-1Zm7.8-1.22a3.77 3.77 0 0 0-6.8-2.26 16.5 16.5 0 0 0-3.04-.48l.85-5.7 2.09.7a3 3 0 0 0 6-.06v-.02a3.03 3.03 0 0 0-3-2.96 2.98 2.98 0 0 0-2.34 1.16l-3.24-1.1a1 1 0 0 0-1.3.8l-1.09 7.17a16.66 16.66 0 0 0-3.34.49 3.77 3.77 0 0 0-6.22 4.23A4.86 4.86 0 0 0 1 16c0 3.92 4.83 7 11 7s11-3.08 11-7a4.86 4.86 0 0 0-.57-2.25 3.78 3.78 0 0 0 .57-1.97ZM19.1 3a1 1 0 1 1-1 1 1.02 1.02 0 0 1 1-1ZM4.77 10a1.76 1.76 0 0 1 .88.25A9.98 9.98 0 0 0 3 11.92v-.14A1.78 1.78 0 0 1 4.78 10ZM12 21c-4.88 0-9-2.29-9-5s4.12-5 9-5 9 2.29 9 5-4.12 5-9 5Zm8.99-9.08a9.98 9.98 0 0 0-2.65-1.67 1.76 1.76 0 0 1 .88-.25A1.78 1.78 0 0 1 21 11.78l-.01.14Z"/>',
 	patreon:
 		'<path d="M22.04 7.6c0-2.8-2.19-5.1-4.75-5.93a15.19 15.19 0 0 0-10.44.55C3.16 3.96 2 7.78 1.95 11.58c-.02 3.12.3 11.36 4.94 11.42 3.45.04 3.97-4.4 5.56-6.55 1.14-1.52 2.6-1.95 4.4-2.4 3.1-.76 5.2-3.2 5.2-6.44Z"/>',
+	slack:
+		'<path d="M5.042 15.165a2.528 2.528 0 0 1-2.52 2.523A2.528 2.528 0 0 1 0 15.165a2.527 2.527 0 0 1 2.522-2.52h2.52v2.52Zm1.271 0a2.527 2.527 0 0 1 2.521-2.52 2.527 2.527 0 0 1 2.521 2.52v6.313A2.528 2.528 0 0 1 8.834 24a2.528 2.528 0 0 1-2.521-2.522v-6.313ZM8.834 5.042a2.528 2.528 0 0 1-2.521-2.52A2.528 2.528 0 0 1 8.834 0a2.528 2.528 0 0 1 2.521 2.522v2.52H8.834Zm0 1.271a2.528 2.528 0 0 1 2.521 2.521 2.528 2.528 0 0 1-2.521 2.521H2.522A2.528 2.528 0 0 1 0 8.834a2.528 2.528 0 0 1 2.522-2.521h6.312Zm10.122 2.521a2.528 2.528 0 0 1 2.522-2.521A2.528 2.528 0 0 1 24 8.834a2.528 2.528 0 0 1-2.522 2.521h-2.522V8.834Zm-1.268 0a2.528 2.528 0 0 1-2.523 2.521 2.527 2.527 0 0 1-2.52-2.521V2.522A2.527 2.527 0 0 1 15.165 0a2.528 2.528 0 0 1 2.523 2.522v6.312Zm-2.523 10.122a2.528 2.528 0 0 1 2.523 2.522A2.528 2.528 0 0 1 15.165 24a2.527 2.527 0 0 1-2.52-2.522v-2.522h2.52Zm0-1.268a2.527 2.527 0 0 1-2.52-2.523 2.526 2.526 0 0 1 2.52-2.52h6.313A2.527 2.527 0 0 1 24 15.165a2.528 2.528 0 0 1-2.522 2.523h-6.313Z"/>',
 };

package/components/Search.astro

@@ -89,8 +89,9 @@ const pagefindTranslations = {
 			// Listen for `/` and `cmd + k` keyboard shortcuts.
 			window.addEventListener('keydown', (e) => {
 				const isInput =
-					document.activeElement &&
-					['input', 'select', 'textarea'].includes(document.activeElement.tagName.toLowerCase());
+					document.activeElement instanceof HTMLElement &&
+					(['input', 'select', 'textarea'].includes(document.activeElement.tagName.toLowerCase()) ||
+						document.activeElement.isContentEditable);
 				if (e.metaKey === true && e.key === 'k') {
 					dialog.open ? closeModal() : openModal();
 					e.preventDefault();

package/components/SiteTitle.astro

@@ -1,10 +1,10 @@
 ---
 import { logos } from 'virtual:starlight/user-images';
 import config from 'virtual:starlight/user-config';
-import { pathWithBase } from '../utils/base';
 import type { Props } from '../props';
+import { formatPath } from '../utils/format-path';
 
-const href = pathWithBase(Astro.props.locale || '/');
+const href = formatPath(Astro.props.locale || '/');
 ---
 
 <a {href} class="site-title sl-flex">

package/index.ts

@@ -4,6 +4,7 @@ import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { starlightAsides } from './integrations/asides';
+import { starlightExpressiveCode } from './integrations/expressive-code';
 import { starlightSitemap } from './integrations/sitemap';
 import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
 import { errorMap } from './utils/error-map';
@@ -37,6 +38,15 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
 					entryPoint: '@astrojs/starlight/index.astro',
 				});
 				const integrations: AstroIntegration[] = [];
+				if (!config.integrations.find(({ name }) => name === 'astro-expressive-code')) {
+					integrations.push(
+						...starlightExpressiveCode({
+							starlightConfig: userConfig,
+							astroConfig: config,
+							useTranslations,
+						})
+					);
+				}
 				if (!config.integrations.find(({ name }) => name === '@astrojs/sitemap')) {
 					integrations.push(starlightSitemap(userConfig));
 				}
@@ -49,7 +59,13 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
 						plugins: [vitePluginStarlightUserConfig(userConfig, config)],
 					},
 					markdown: {
-						remarkPlugins: [...starlightAsides()],
+						remarkPlugins: [
+							...starlightAsides({
+								starlightConfig: userConfig,
+								astroConfig: config,
+								useTranslations,
+							}),
+						],
 						rehypePlugins: [rehypeRtlCodeSupport()],
 						shikiConfig:
 							// Configure Shiki theme if the user is using the default github-dark theme.

package/integrations/asides.ts

@@ -1,10 +1,19 @@
-import type { AstroUserConfig } from 'astro';
+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 remarkDirective from 'remark-directive';
 import type { Plugin, Transformer } from 'unified';
 import { remove } from 'unist-util-remove';
 import { visit } from 'unist-util-visit';
+import type { StarlightConfig } from '../types';
+import type { createTranslationSystemFromFs } from '../utils/translations-fs';
+import { pathToLocale } from './shared/pathToLocale';
+
+interface AsidesOptions {
+	starlightConfig: { locales: StarlightConfig['locales'] };
+	astroConfig: { root: AstroConfig['root']; srcDir: AstroConfig['srcDir'] };
+	useTranslations: ReturnType<typeof createTranslationSystemFromFs>;
+}
 
 /** Hacky function that generates an mdast HTML tree ready for conversion to HTML by rehype. */
 function h(el: string, attrs: Properties = {}, children: any[] = []): P {
@@ -50,19 +59,11 @@ function s(el: string, attrs: Properties = {}, children: any[] = []): P {
  * </Aside>
  * ```
  */
-function remarkAsides(): Plugin<[], Root> {
+function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 	type Variant = 'note' | 'tip' | 'caution' | 'danger';
 	const variants = new Set(['note', 'tip', 'caution', 'danger']);
 	const isAsideVariant = (s: string): s is Variant => variants.has(s);
 
-	// TODO: hook these up for i18n once the design for translating strings is ready
-	const defaultTitles = {
-		note: 'Note',
-		tip: 'Tip',
-		caution: 'Caution',
-		danger: 'Danger',
-	};
-
 	const iconPaths = {
 		// Information icon
 		note: [
@@ -95,7 +96,9 @@ function remarkAsides(): Plugin<[], Root> {
 		],
 	};
 
-	const transformer: Transformer<Root> = (tree) => {
+	const transformer: Transformer<Root> = (tree, file) => {
+		const locale = pathToLocale(file.history[0], options);
+		const t = options.useTranslations(locale);
 		visit(tree, (node, index, parent) => {
 			if (!parent || index === null || node.type !== 'containerDirective') {
 				return;
@@ -107,7 +110,7 @@ function remarkAsides(): Plugin<[], Root> {
 			// its children, but we want to pass it as the title prop to <Aside>, so
 			// we iterate over the children, find a directive label, store it for the
 			// title prop, and remove the paragraph from children.
-			let title = defaultTitles[variant];
+			let title = t(`aside.${variant}`);
 			remove(node, (child): boolean | void => {
 				if (child.data?.directiveLabel) {
 					if (
@@ -157,6 +160,6 @@ function remarkAsides(): Plugin<[], Root> {
 
 type RemarkPlugins = NonNullable<NonNullable<AstroUserConfig['markdown']>['remarkPlugins']>;
 
-export function starlightAsides(): RemarkPlugins {
-	return [remarkDirective, remarkAsides()];
+export function starlightAsides(options: AsidesOptions): RemarkPlugins {
+	return [remarkDirective, remarkAsides(options)];
 }

package/integrations/expressive-code/exports.ts

@@ -0,0 +1,36 @@
+/**
+ * @file This file is exported by Starlight as `@astrojs/starlight/expressive-code`
+ * and can be used in your site's configuration to customize Expressive Code.
+ *
+ * It provides access to all of the Expressive Code classes and functions without having
+ * to install `astro-expressive-code` as an additional dependency into your project
+ * (and thereby risiking version conflicts).
+ *
+ * For example, you can use this to load custom themes from a JSONC file (JSON with comments)
+ * that would otherwise be difficult to import, and pass them to the `themes` option:
+ *
+ * @example
+ * ```js
+ * // astro.config.mjs
+ * import fs from 'node:fs';
+ * import { defineConfig } from 'astro/config';
+ * import starlight from '@astrojs/starlight';
+ * import { ExpressiveCodeTheme } from '@astrojs/starlight/expressive-code';
+ *
+ * const jsoncString = fs.readFileSync(new URL(`./my-theme.jsonc`, import.meta.url), 'utf-8');
+ * const myTheme = ExpressiveCodeTheme.fromJSONString(jsoncString);
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     starlight({
+ *       title: 'My Starlight site',
+ *       expressiveCode: {
+ *         themes: [myTheme],
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+export * from 'astro-expressive-code';

package/integrations/expressive-code/index.ts

@@ -0,0 +1,156 @@
+import {
+	astroExpressiveCode,
+	type AstroExpressiveCodeOptions,
+	addClassName,
+} from 'astro-expressive-code';
+import type { AstroConfig, AstroIntegration } from 'astro';
+import type { StarlightConfig } from '../../types';
+import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
+import { pathToLocale } from '../shared/pathToLocale';
+import {
+	applyStarlightUiThemeColors,
+	preprocessThemes,
+	type ThemeObjectOrBundledThemeName,
+} from './theming';
+import { addTranslations } from './translations';
+
+export type StarlightExpressiveCodeOptions = Omit<AstroExpressiveCodeOptions, 'themes'> & {
+	/**
+	 * Set the themes used to style code blocks.
+	 *
+	 * See the [Expressive Code `themes` documentation](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#themes)
+	 * for details of the supported theme formats.
+	 *
+	 * Starlight uses the dark and light variants of Sarah Drasner’s
+	 * [Night Owl theme](https://github.com/sdras/night-owl-vscode-theme) by default.
+	 *
+	 * If you provide at least one dark and one light theme, Starlight will automatically keep
+	 * the active code block theme in sync with the current site theme. Configure this behavior
+	 * with the [`useStarlightDarkModeSwitch`](#usestarlightdarkmodeswitch) option.
+	 *
+	 * Defaults to `['starlight-dark', 'starlight-light']`.
+	 */
+	themes?: ThemeObjectOrBundledThemeName[] | undefined;
+	/**
+	 * When `true`, code blocks automatically switch between light and dark themes when the
+	 * site theme changes.
+	 *
+	 * When `false`, you must manually add CSS to handle switching between multiple themes.
+	 *
+	 * **Note**: When setting `themes`, you must provide at least one dark and one light theme
+	 * for the Starlight dark mode switch to work.
+	 *
+	 * Defaults to `true`.
+	 */
+	useStarlightDarkModeSwitch?: boolean | undefined;
+	/**
+	 * When `true`, Starlight's CSS variables are used for the colors of code block UI elements
+	 * (backgrounds, buttons, shadows etc.), matching the
+	 * [site color theme](/guides/css-and-tailwind/#theming).
+	 *
+	 * When `false`, the colors provided by the active syntax highlighting theme are used for
+	 * these elements.
+	 *
+	 * Defaults to `true` if the `themes` option is not set (= you are using Starlight's
+	 * default themes), and `false` otherwise.
+	 *
+	 * **Note**: When manually setting this to `true` with your custom set of `themes`, you must
+	 * provide at least one dark and one light theme to ensure proper color contrast.
+	 */
+	useStarlightUiThemeColors?: boolean | undefined;
+};
+
+export const starlightExpressiveCode = ({
+	astroConfig,
+	starlightConfig,
+	useTranslations,
+}: {
+	astroConfig: Pick<AstroConfig, 'root' | 'srcDir'>;
+	starlightConfig: StarlightConfig;
+	useTranslations: ReturnType<typeof createTranslationSystemFromFs>;
+}): AstroIntegration[] => {
+	const { locales, expressiveCode } = starlightConfig;
+	if (expressiveCode === false) return [];
+	const config: StarlightExpressiveCodeOptions =
+		typeof expressiveCode === 'object' ? expressiveCode : {};
+
+	const {
+		themes: themesInput,
+		customizeTheme,
+		styleOverrides: { textMarkers: textMarkersStyleOverrides, ...otherStyleOverrides } = {},
+		useStarlightDarkModeSwitch,
+		useStarlightUiThemeColors = config.themes === undefined,
+		plugins = [],
+		...rest
+	} = config;
+
+	// Handle the `themes` option
+	const themes = preprocessThemes(themesInput);
+	if (useStarlightUiThemeColors === true && themes.length < 2) {
+		console.warn(
+			`*** Warning: Using the config option "useStarlightUiThemeColors: true" ` +
+				`with a single theme is not recommended. For better color contrast, ` +
+				`please provide at least one dark and one light theme.\n`
+		);
+	}
+
+	// Add the `not-content` class to all rendered blocks to prevent them from being affected
+	// by Starlight's default content styles
+	plugins.push({
+		name: 'Starlight Plugin',
+		hooks: {
+			postprocessRenderedBlock: ({ renderData }) => {
+				addClassName(renderData.blockAst, 'not-content');
+			},
+		},
+	});
+
+	// Add Expressive Code UI translations (if any) for all defined locales
+	addTranslations(locales, useTranslations);
+
+	return [
+		astroExpressiveCode({
+			themes,
+			customizeTheme: (theme) => {
+				if (useStarlightUiThemeColors) {
+					applyStarlightUiThemeColors(theme);
+				}
+				if (customizeTheme) {
+					theme = customizeTheme(theme) ?? theme;
+				}
+				return theme;
+			},
+			themeCssSelector: (theme, { styleVariants }) => {
+				// If one dark and one light theme are available, and the user has not disabled it,
+				// generate theme CSS selectors compatible with Starlight's dark mode switch
+				if (useStarlightDarkModeSwitch !== false && styleVariants.length >= 2) {
+					const baseTheme = styleVariants[0]?.theme;
+					const altTheme = styleVariants.find((v) => v.theme.type !== baseTheme?.type)?.theme;
+					if (theme === baseTheme || theme === altTheme) return `[data-theme='${theme.type}']`;
+				}
+				// Return the default selector
+				return `[data-theme='${theme.name}']`;
+			},
+			styleOverrides: {
+				borderRadius: '0px',
+				borderWidth: '1px',
+				codePaddingBlock: '0.75rem',
+				codePaddingInline: '1rem',
+				codeFontFamily: 'var(--__sl-font-mono)',
+				codeFontSize: 'var(--sl-text-code)',
+				codeLineHeight: 'var(--sl-line-height)',
+				uiFontFamily: 'var(--__sl-font)',
+				textMarkers: {
+					lineDiffIndicatorMarginLeft: '0.25rem',
+					defaultChroma: '45',
+					backgroundOpacity: '60%',
+					...textMarkersStyleOverrides,
+				},
+				...otherStyleOverrides,
+			},
+			getBlockLocale: ({ file }) => pathToLocale(file.path, { starlightConfig, astroConfig }),
+			plugins,
+			...rest,
+		}),
+	];
+};