@astrojs/starlight 0.24.4 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @astrojs/starlight
 
+## 0.25.0
+
+### Minor Changes
+
+- [#2025](https://github.com/withastro/starlight/pull/2025) [`47f32c1`](https://github.com/withastro/starlight/commit/47f32c196c5d840a6a45799ddf123d17c77274b0) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Removes the `/` search shortcut for [accessibility reasons](https://www.w3.org/WAI/WCAG21/Understanding/character-key-shortcuts.html).
+
+  ⚠️ **Potentially breaking change:** The `search.shortcutLabel` UI string has been removed. If you were using this string in your custom UI, you will need to update your code.
+
+- [#2064](https://github.com/withastro/starlight/pull/2064) [`c5b47cb`](https://github.com/withastro/starlight/commit/c5b47cbe1242f0b29b9212db72fe26590ab57d88) Thanks [@SnowDingo](https://github.com/SnowDingo)! - Improves styling of Markdown tables to work better in different contexts, including against different background colours like when used in asides.
+
+- [#2031](https://github.com/withastro/starlight/pull/2031) [`2bab648`](https://github.com/withastro/starlight/commit/2bab648be9ddc6bfe05562650b773f5158a9ed42) Thanks [@delucis](https://github.com/delucis)! - Makes sidebar entry parsing stricter in Starlight config
+
+  **⚠️ Potentially breaking change:** Previously Starlight would accept a sidebar entry that matched one of its expected shapes, even if it included additional properties. For example, including both `link` and `items` was considered valid, with `items` being ignored. Now, it is an error to include more than one of `link`, `items`, or `autogenerate` in a sidebar entry.
+
+  If you see errors after updating, look for sidebar entries in the Starlight configuration in `astro.config.mjs` that include too many keys and remove the one that was previously ignored.
+
+- [#1874](https://github.com/withastro/starlight/pull/1874) [`eeba06e`](https://github.com/withastro/starlight/commit/eeba06ea7df962e8f0520e145d28b8c17cd32c18) Thanks [@lorenzolewis](https://github.com/lorenzolewis)! - Adds a new syntax for specifying sidebar link items for internal links
+
+  You can now specify an internal page using only its slug, either as a string, or as an object with a `slug` property:
+
+  ```js
+  starlight({
+    title: 'Docs with easier sidebars',
+    sidebar: ['getting-started', { slug: 'guides/installation' }],
+  });
+  ```
+
+  Starlight will use the linked page’s frontmatter to configure the sidebar link.
+
+### Patch Changes
+
+- [#2081](https://github.com/withastro/starlight/pull/2081) [`f0181d2`](https://github.com/withastro/starlight/commit/f0181d2689248a46ff3eb6fc604bfcd95d4cb1aa) Thanks [@andrii-bodnar](https://github.com/andrii-bodnar)! - Updates the Ukrainian UI translations
+
+## 0.24.5
+
+### Patch Changes
+
+- [#2062](https://github.com/withastro/starlight/pull/2062) [`5ac0ac6`](https://github.com/withastro/starlight/commit/5ac0ac6614e3c45d810a1594a2009d3febfa2793) Thanks [@evadecker](https://github.com/evadecker)! - Increase theme and language select inline padding
+
+- [#2056](https://github.com/withastro/starlight/pull/2056) [`87e9ad0`](https://github.com/withastro/starlight/commit/87e9ad029c9730fca8df66e35828b57cd0872a61) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes an issue preventing remark plugins injected by Starlight plugins to handle Markdown text and leaf directives.
+
+- [#2063](https://github.com/withastro/starlight/pull/2063) [`3ee1a94`](https://github.com/withastro/starlight/commit/3ee1a9404db25f5776a3c1ecd248614f64db46ae) Thanks [@delucis](https://github.com/delucis)! - Translate `fileTree.directory` and `aside.*` UI string into Norwegian (Bokmål).
+
+- [#2054](https://github.com/withastro/starlight/pull/2054) [`dbfd3ee`](https://github.com/withastro/starlight/commit/dbfd3eeccacb5f5b77d75213dac3b30dc0be6deb) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes an issue when using the `<StarlightPage>` component in a custom page with a user-defined `srcDir` configuration.
+
 ## 0.24.4
 
 ### Patch Changes

package/__e2e__/collection-config.test.ts

@@ -0,0 +1,12 @@
+import { expect, testFactory } from './test-utils';
+
+const test = await testFactory('./fixtures/custom-src-dir/');
+
+test('builds a custom page using the `<StarlightPage>` component and a custom `srcDir`', async ({
+	page,
+	starlight,
+}) => {
+	await starlight.goto('/custom');
+
+	await expect(page.getByText('Hello')).toBeVisible();
+});

package/__e2e__/fixtures/basics/astro.config.mjs

@@ -5,6 +5,7 @@ export default defineConfig({
 	integrations: [
 		starlight({
 			title: 'Basics',
+			pagefind: false,
 		}),
 	],
 });

package/__e2e__/fixtures/custom-src-dir/astro.config.mjs

@@ -0,0 +1,12 @@
+import starlight from '@astrojs/starlight';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+	srcDir: './www',
+	integrations: [
+		starlight({
+			title: 'Custom src directory',
+			pagefind: false,
+		}),
+	],
+});

package/__e2e__/fixtures/custom-src-dir/node_modules/.bin/astro

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/starlight/starlight/node_modules/.pnpm/astro@4.10.2_@types+node@18.16.19_typescript@5.4.5/node_modules/astro/node_modules:/home/runner/work/starlight/starlight/node_modules/.pnpm/astro@4.10.2_@types+node@18.16.19_typescript@5.4.5/node_modules:/home/runner/work/starlight/starlight/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/starlight/starlight/node_modules/.pnpm/astro@4.10.2_@types+node@18.16.19_typescript@5.4.5/node_modules/astro/node_modules:/home/runner/work/starlight/starlight/node_modules/.pnpm/astro@4.10.2_@types+node@18.16.19_typescript@5.4.5/node_modules:/home/runner/work/starlight/starlight/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../astro/astro.js" "$@"
+else
+  exec node  "$basedir/../astro/astro.js" "$@"
+fi

package/__e2e__/fixtures/custom-src-dir/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@e2e/custom-src-dir",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/starlight": "workspace:*",
+    "astro": "^4.10.2"
+  }
+}

package/__e2e__/fixtures/custom-src-dir/www/content/config.ts

@@ -0,0 +1,6 @@
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ schema: docsSchema() }),
+};

package/__e2e__/fixtures/custom-src-dir/www/env.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />

package/__e2e__/fixtures/custom-src-dir/www/pages/custom.astro

@@ -0,0 +1,7 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+---
+
+<StarlightPage frontmatter={{ title: 'A custom page' }}>
+	<p>Hello</p>
+</StarlightPage>

package/__e2e__/test-utils.ts

@@ -4,6 +4,8 @@ import { build, preview } from 'astro';
 
 export { expect, type Locator } from '@playwright/test';
 
+process.env.ASTRO_TELEMETRY_DISABLED = 'true';
+
 // Setup a test environment that will build and start a preview server for a given fixture path and
 // provide a Starlight Playwright fixture accessible from within all tests.
 export async function testFactory(fixturePath: string) {

package/components/Search.astro

@@ -20,17 +20,17 @@ const pagefindTranslations = {
 	data-translations={JSON.stringify(pagefindTranslations)}
 	data-strip-trailing-slash={project.trailingSlash === 'never'}
 >
-	<button data-open-modal disabled>
-		{
-			/* The span is `aria-hidden` because it is not shown on small screens. Instead, the icon label is used for accessibility purposes. */
-		}
-		<Icon name="magnifier" label={labels['search.label']} />
+	<button
+		data-open-modal
+		disabled
+		aria-label={labels['search.label']}
+		aria-keyshortcuts="Control+K"
+	>
+		<Icon name="magnifier" />
 		<span class="sl-hidden md:sl-block" aria-hidden="true">{labels['search.label']}</span>
-		<Icon
-			name="forward-slash"
-			class="sl-hidden md:sl-block"
-			label={labels['search.shortcutLabel']}
-		/>
+		<kbd class="sl-hidden md:sl-flex" style="display: none;">
+			<kbd>{labels['search.ctrlKey']}</kbd><kbd>K</kbd>
+		</kbd>
 	</button>
 
 	<dialog style="padding:0" aria-label={labels['search.label']}>
@@ -56,6 +56,27 @@ const pagefindTranslations = {
 	</dialog>
 </site-search>
 
+{
+	/**
+	 * This is intentionally inlined to avoid briefly showing an invalid shortcut.
+	 * Purposely using the deprecated `navigator.platform` property to detect Apple devices, as the
+	 * user agent is spoofed by some browsers when opening the devtools.
+	 */
+}
+<script is:inline>
+	(() => {
+		const openBtn = document.querySelector('button[data-open-modal]');
+		const shortcut = openBtn?.querySelector('kbd');
+		if (!openBtn || !(shortcut instanceof HTMLElement)) return;
+		const platformKey = shortcut.querySelector('kbd');
+		if (platformKey && /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform)) {
+			platformKey.textContent = '⌘';
+			openBtn.setAttribute('aria-keyshortcuts', 'Meta+K');
+		}
+		shortcut.style.display = '';
+	})();
+</script>
+
 <script>
 	class SiteSearch extends HTMLElement {
 		constructor() {
@@ -96,18 +117,11 @@ const pagefindTranslations = {
 				window.removeEventListener('click', onClick);
 			});
 
-			// Listen for `/`, `ctrl + k`, and `cmd + k` keyboard shortcuts.
+			// Listen for `ctrl + k` and `cmd + k` keyboard shortcuts.
 			window.addEventListener('keydown', (e) => {
-				const isInput =
-					document.activeElement instanceof HTMLElement &&
-					(['input', 'select', 'textarea'].includes(document.activeElement.tagName.toLowerCase()) ||
-						document.activeElement.isContentEditable);
 				if ((e.metaKey === true || e.ctrlKey === true) && e.key === 'k') {
 					dialog.open ? closeModal() : openModal();
 					e.preventDefault();
-				} else if (e.key === '/' && !dialog.open && !isInput) {
-					openModal();
-					e.preventDefault();
 				}
 			});
 
@@ -169,7 +183,7 @@ const pagefindTranslations = {
 			border: 1px solid var(--sl-color-gray-5);
 			border-radius: 0.5rem;
 			padding-inline-start: 0.75rem;
-			padding-inline-end: 1rem;
+			padding-inline-end: 0.5rem;
 			background-color: var(--sl-color-black);
 			color: var(--sl-color-gray-2);
 			font-size: var(--sl-text-sm);
@@ -186,6 +200,18 @@ const pagefindTranslations = {
 		}
 	}
 
+	button > kbd {
+		border-radius: 0.25rem;
+		font-size: var(--sl-text-2xs);
+		gap: 0.25em;
+		padding-inline: 0.375rem;
+		background-color: var(--sl-color-gray-6);
+	}
+
+	kbd {
+		font-family: var(--__sl-font);
+	}
+
 	dialog {
 		margin: 0;
 		background-color: var(--sl-color-gray-6);

package/components/Select.astro

@@ -31,6 +31,7 @@ interface Props {
 	label {
 		--sl-label-icon-size: 0.875rem;
 		--sl-caret-size: 1.25rem;
+		--sl-inline-padding: 0.5rem;
 		position: relative;
 		display: flex;
 		align-items: center;
@@ -62,8 +63,10 @@ interface Props {
 	select {
 		border: 0;
 		padding-block: 0.625rem;
-		padding-inline: calc(var(--sl-label-icon-size) + 0.25rem) calc(var(--sl-caret-size) + 0.25rem);
-		width: var(--sl-select-width);
+		padding-inline: calc(var(--sl-label-icon-size) + var(--sl-inline-padding) + 0.25rem)
+			calc(var(--sl-caret-size) + var(--sl-inline-padding) + 0.25rem);
+		margin-inline: calc(var(--sl-inline-padding) * -1);
+		width: calc(var(--sl-select-width) + var(--sl-inline-padding) * 2);
 		background-color: transparent;
 		text-overflow: ellipsis;
 		color: inherit;

package/index.ts

@@ -3,7 +3,7 @@ import type { AstroIntegration } from 'astro';
 import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { starlightAsides } from './integrations/asides';
+import { starlightAsides, starlightDirectivesRestorationIntegration } from './integrations/asides';
 import { starlightExpressiveCode } from './integrations/expressive-code/index';
 import { starlightSitemap } from './integrations/sitemap';
 import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
@@ -73,6 +73,10 @@ export default function StarlightIntegration({
 				if (!allIntegrations.find(({ name }) => name === '@astrojs/mdx')) {
 					integrations.push(mdx({ optimize: true }));
 				}
+				// Add Starlight directives restoration integration at the end of the list so that remark
+				// plugins injected by Starlight plugins through Astro integrations can handle text and
+				// leaf directives before they are transformed back to their original form.
+				integrations.push(starlightDirectivesRestorationIntegration());
 
 				// Add integrations immediately after Starlight in the config array.
 				// e.g. if a user has `integrations: [starlight(), tailwind()]`, then the order will be

package/integrations/asides.ts

@@ -1,6 +1,6 @@
 /// <reference types="mdast-util-directive" />
 
-import type { AstroConfig, AstroUserConfig } from 'astro';
+import type { AstroConfig, AstroIntegration, AstroUserConfig } from 'astro';
 import { h as _h, s as _s, type Properties } from 'hastscript';
 import type { Node, Paragraph as P, Parent, Root } from 'mdast';
 import {
@@ -146,7 +146,6 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 				return;
 			}
 			if (node.type === 'textDirective' || node.type === 'leafDirective') {
-				transformUnhandledDirective(node, index, parent);
 				return;
 			}
 			const variant = node.name;
@@ -210,3 +209,43 @@ type RemarkPlugins = NonNullable<NonNullable<AstroUserConfig['markdown']>['remar
 export function starlightAsides(options: AsidesOptions): RemarkPlugins {
 	return [remarkDirective, remarkAsides(options)];
 }
+
+export function remarkDirectivesRestoration() {
+	return function transformer(tree: Root) {
+		visit(tree, (node, index, parent) => {
+			if (
+				index !== undefined &&
+				parent &&
+				(node.type === 'textDirective' || node.type === 'leafDirective')
+			) {
+				transformUnhandledDirective(node, index, parent);
+				return;
+			}
+		});
+	};
+}
+
+/**
+ * Directives not handled by Starlight are transformed back to their original form to avoid
+ * breaking user content.
+ * To allow remark plugins injected by Starlight plugins through Astro integrations to handle
+ * such directives, we need to restore unhandled text and leaf directives back to their original
+ * form only after all these other plugins have run.
+ * To do so, we run a remark plugin restoring these directives back to their original form from
+ * another Astro integration that runs after all the ones that may have been injected by Starlight
+ * plugins.
+ */
+export function starlightDirectivesRestorationIntegration(): AstroIntegration {
+	return {
+		name: 'starlight-directives-restoration',
+		hooks: {
+			'astro:config:setup': ({ updateConfig }) => {
+				updateConfig({
+					markdown: {
+						remarkPlugins: [remarkDirectivesRestoration],
+					},
+				});
+			},
+		},
+	};
+}

package/integrations/virtual-user-config.ts

@@ -50,7 +50,7 @@ export function vitePluginStarlightUserConfig(
 			: 'export const logos = {};',
 		'virtual:starlight/collection-config': `let userCollections;
 			try {
-				userCollections = (await import('/src/content/config.ts')).collections;
+				userCollections = (await import('${new URL('./content/config.ts', srcDir).pathname}')).collections;
 			} catch {}
 			export const collections = userCollections;`,
 		...virtualComponentModules,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.24.4",
+  "version": "0.25.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -175,7 +175,7 @@
   },
   "devDependencies": {
     "@astrojs/markdown-remark": "^5.1.0",
-    "@playwright/test": "^1.44.1",
+    "@playwright/test": "^1.45.0",
     "@types/node": "^18.16.19",
     "@vitest/coverage-v8": "^1.6.0",
     "astro": "^4.10.2",

package/playwright.config.ts

@@ -12,4 +12,6 @@ export default defineConfig({
 		},
 	],
 	testMatch: '__e2e__/*.test.ts',
+	timeout: 40 * 1_000,
+	workers: 1,
 });

package/schemas/i18n.ts

@@ -55,9 +55,11 @@ function starlightI18nSchema() {
 
 			'search.label': z.string().describe('Text displayed in the search bar.'),
 
-			'search.shortcutLabel': z
+			'search.ctrlKey': z
 				.string()
-				.describe('Accessible label for the shortcut key to open the search modal.'),
+				.describe(
+					'Visible representation of the Control key potentially used in the shortcut key to open the search modal.'
+				),
 
 			'search.cancelLabel': z
 				.string()

package/schemas/sidebar.ts

@@ -33,7 +33,7 @@ const SidebarLinkItemSchema = SidebarBaseSchema.extend({
 	link: z.string(),
 	/** HTML attributes to add to the link item. */
 	attrs: SidebarLinkItemHTMLAttributesSchema(),
-});
+}).strict();
 export type SidebarLinkItem = z.infer<typeof SidebarLinkItemSchema>;
 
 const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
@@ -50,7 +50,7 @@ const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
 		/** How many directories deep to include from this directory in the sidebar. Default: `Infinity`. */
 		// depth: z.number().optional(),
 	}),
-});
+}).strict();
 export type AutoSidebarGroup = z.infer<typeof AutoSidebarGroupSchema>;
 
 type ManualSidebarGroupInput = z.input<typeof SidebarGroupSchema> & {
@@ -58,6 +58,8 @@ type ManualSidebarGroupInput = z.input<typeof SidebarGroupSchema> & {
 	items: Array<
 		| z.input<typeof SidebarLinkItemSchema>
 		| z.input<typeof AutoSidebarGroupSchema>
+		| z.input<typeof InternalSidebarLinkItemSchema>
+		| z.input<typeof InternalSidebarLinkItemShorthandSchema>
 		| ManualSidebarGroupInput
 	>;
 };
@@ -67,6 +69,8 @@ type ManualSidebarGroupOutput = z.output<typeof SidebarGroupSchema> & {
 	items: Array<
 		| z.output<typeof SidebarLinkItemSchema>
 		| z.output<typeof AutoSidebarGroupSchema>
+		| z.output<typeof InternalSidebarLinkItemSchema>
+		| z.output<typeof InternalSidebarLinkItemShorthandSchema>
 		| ManualSidebarGroupOutput
 	>;
 };
@@ -78,13 +82,34 @@ const ManualSidebarGroupSchema: z.ZodType<
 > = SidebarGroupSchema.extend({
 	/** Array of links and subcategories to display in this category. */
 	items: z.lazy(() =>
-		z.union([SidebarLinkItemSchema, ManualSidebarGroupSchema, AutoSidebarGroupSchema]).array()
+		z
+			.union([
+				SidebarLinkItemSchema,
+				ManualSidebarGroupSchema,
+				AutoSidebarGroupSchema,
+				InternalSidebarLinkItemSchema,
+				InternalSidebarLinkItemShorthandSchema,
+			])
+			.array()
 	),
+}).strict();
+
+const InternalSidebarLinkItemSchema = SidebarBaseSchema.partial({ label: true }).extend({
+	/** The link to this item’s content. Must be a slug of a Content Collection entry. */
+	slug: z.string(),
+	/** HTML attributes to add to the link item. */
+	attrs: SidebarLinkItemHTMLAttributesSchema(),
 });
+const InternalSidebarLinkItemShorthandSchema = z
+	.string()
+	.transform((slug) => InternalSidebarLinkItemSchema.parse({ slug }));
+export type InternalSidebarLinkItem = z.output<typeof InternalSidebarLinkItemSchema>;
 
 export const SidebarItemSchema = z.union([
 	SidebarLinkItemSchema,
 	ManualSidebarGroupSchema,
 	AutoSidebarGroupSchema,
+	InternalSidebarLinkItemSchema,
+	InternalSidebarLinkItemShorthandSchema,
 ]);
 export type SidebarItem = z.infer<typeof SidebarItemSchema>;

package/style/markdown.css

@@ -100,17 +100,40 @@
 	padding-inline-start: 1rem;
 }
 
+/* Table styling */
 .sl-markdown-content table:not(:where(.not-content *)) {
 	display: block;
 	overflow: auto;
-	border-collapse: collapse;
-}
-.sl-markdown-content tr:nth-child(2n):not(:where(.not-content *)) {
-	background-color: var(--sl-color-gray-7, var(--sl-color-gray-6));
+	border-spacing: 0;
 }
 .sl-markdown-content :is(th, td):not(:where(.not-content *)) {
-	border: 1px solid var(--sl-color-hairline-light);
-	padding: 0.375rem 0.8125rem;
+	border-bottom: 1px solid var(--sl-color-gray-5);
+	padding: 0.5rem 1rem;
+	/* Align text to the top of the row in multiline tables. */
+	vertical-align: baseline;
+}
+.sl-markdown-content :is(th:first-child, td:first-child):not(:where(.not-content *)) {
+	padding-inline-start: 0;
+}
+.sl-markdown-content :is(th:last-child, td:last-child):not(:where(.not-content *)) {
+	padding-inline-end: 0;
+}
+.sl-markdown-content th:not(:where(.not-content *)) {
+	color: var(--sl-color-white);
+	font-weight: 600;
+}
+/* Align headings to the start of the line unless set by the `align` attribute. */
+.sl-markdown-content th:not([align]):not(:where(.not-content *)) {
+	text-align: start;
+}
+/* Table styles inside asides */
+.sl-markdown-content .starlight-aside :is(th, td):not(:where(.not-content *)) {
+	border-color: var(--sl-color-gray-4);
+}
+@supports (border-color: color-mix(in srgb, var(--sl-color-asides-text-accent) 30%, transparent)) {
+	.sl-markdown-content .starlight-aside :is(th, td):not(:where(.not-content *)) {
+		border-color: color-mix(in srgb, var(--sl-color-asides-text-accent) 30%, transparent);
+	}
 }
 
 .sl-markdown-content hr:not(:where(.not-content *)) {

package/style/props.css

@@ -58,6 +58,7 @@
 		0px 4px 2px hsla(0, 0%, 0%, 0.25);
 
 	/* Text size and line height */
+	--sl-text-2xs: 0.75rem; /* 12px */
 	--sl-text-xs: 0.8125rem; /* 13px */
 	--sl-text-sm: 0.875rem; /* 14px */
 	--sl-text-base: 1rem; /* 16px */

package/translations/ar.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "تخطَّ إلى المحتوى",
   "search.label": "ابحث",
-  "search.shortcutLabel": "(إضغط / للبحث)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "إلغاء",
   "search.devWarning": "البحث متوفر فقط في بنيات اﻹنتاج. \n جرب بناء المشروع ومعاينته على جهازك",
   "themeSelect.accessibleLabel": "اختر سمة",

package/translations/cs.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Přeskočit na obsah",
   "search.label": "Hledat",
-  "search.shortcutLabel": "(Vyhledejte stisknutím /)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Zrušit",
   "search.devWarning": "Vyhledávání je dostupné pouze v produkčních sestaveních. \nZkuste sestavit a zobrazit náhled webu a otestovat jej lokálně.",
   "themeSelect.accessibleLabel": "Vyberte motiv",

package/translations/da.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Gå til indhold",
   "search.label": "Søg",
-  "search.shortcutLabel": "(Tryk / for at søge)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Annuller",
   "search.devWarning": "Søgning er kun tilgængeligt i produktions versioner. \nPrøv at bygge siden og forhåndsvis den for at teste det lokalt.",
   "themeSelect.accessibleLabel": "Vælg tema",

package/translations/de.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Zum Inhalt springen",
   "search.label": "Suchen",
-  "search.shortcutLabel": "(Drücke / zum Suchen)",
+  "search.ctrlKey": "Strg",
   "search.cancelLabel": "Abbrechen",
   "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
   "themeSelect.accessibleLabel": "Farbschema wählen",

package/translations/en.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Skip to content",
   "search.label": "Search",
-  "search.shortcutLabel": "(Press / to Search)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Cancel",
   "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
   "themeSelect.accessibleLabel": "Select theme",

package/translations/es.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Saltearse al contenido",
   "search.label": "Buscar",
-  "search.shortcutLabel": "(Presiona / para buscar)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Interrumpir",
   "search.devWarning": "La búsqueda solo está disponible en las versiones de producción.  \nIntenta construir y previsualizar el sitio para probarlo localmente.",
   "themeSelect.accessibleLabel": "Seleccionar tema",

package/translations/fa.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "رفتن به محتوا",
   "search.label": "جستجو",
-  "search.shortcutLabel": "(برای جستجو / را فشار دهید)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "لغو",
   "search.devWarning": "جستجو تنها در نسخه‌های تولیدی در دسترس است. \nسعی کنید سایت را بسازید و پیش‌نمایش آن را به صورت محلی آزمایش کنید.",
   "themeSelect.accessibleLabel": "انتخاب پوسته",

package/translations/fr.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Aller au contenu",
   "search.label": "Rechercher",
-  "search.shortcutLabel": "(Presser / pour rechercher)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Annuler",
   "search.devWarning": "La recherche est disponible uniquement en mode production. \nEssayez de construire puis de prévisualiser votre site pour tester la recherche localement.",
   "themeSelect.accessibleLabel": "Selectionner le thème",

package/translations/gl.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Ir ao contido",
   "search.label": "Busca",
-  "search.shortcutLabel": "(Preme / para Busca)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Deixar",
   "search.devWarning": "A busca só está dispoñible nas versións de producción. \nTrata de construir e ollear o sitio para probalo localmente.",
   "themeSelect.accessibleLabel": "Seleciona tema",

package/translations/he.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "דלגו לתוכן",
   "search.label": "חיפוש",
-  "search.shortcutLabel": "(לחצו / כדי לחפש)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "ביטול",
   "search.devWarning": "החיפוש זמין רק בסביבת ייצור. \nנסו לבנות ולהציג תצוגה מקדימה של האתר כדי לבדוק אותו באופן מקומי.",
   "themeSelect.accessibleLabel": "בחרו פרופיל צבע",

package/translations/hi.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "इसे छोड़कर कंटेंट पर जाएं",
   "search.label": "खोजें",
-  "search.shortcutLabel": "(खोजने के लिए / दबाएँ)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "रद्द करे",
   "search.devWarning": "खोज केवल उत्पादन बिल्ड में उपलब्ध है। \nस्थानीय स्तर पर परीक्षण करने के लिए साइट बनाए और उसका पूर्वावलोकन करने का प्रयास करें।",
   "themeSelect.accessibleLabel": "थीम चुनें",

package/translations/id.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Lewati ke konten",
   "search.label": "Pencarian",
-  "search.shortcutLabel": "(Tekan / untuk mencari)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Batal",
   "search.devWarning": "Pencarian hanya tersedia pada build produksi. \nLakukan proses build dan pratinjau situs Anda sebelum mencoba di lingkungan lokal.",
   "themeSelect.accessibleLabel": "Pilih tema",

package/translations/it.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Salta ai contenuti",
   "search.label": "Cerca",
-  "search.shortcutLabel": "(Usa / per cercare)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Cancella",
   "search.devWarning": "La ricerca è disponibile solo nelle build di produzione. \nProvare ad eseguire il processo di build e visualizzare la preview del sito per testarlo localmente.",
   "themeSelect.accessibleLabel": "Seleziona tema",

package/translations/ja.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "コンテンツにスキップ",
   "search.label": "検索",
-  "search.shortcutLabel": "（/を押して検索）",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "キャンセル",
   "search.devWarning": "検索はプロダクションビルドでのみ利用可能です。\nローカルでテストするには、サイトをビルドしてプレビューしてください。",
   "themeSelect.accessibleLabel": "テーマの選択",

package/translations/ko.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "컨텐츠로 건너뛰기",
   "search.label": "검색",
-  "search.shortcutLabel": "(검색하려면 / 를 누르세요)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "취소",
   "search.devWarning": "검색 기능은 운영 환경에서만 사용할 수 있습니다. \n로컬에서 테스트하려면 사이트를 빌드하고 미리보기를 해보세요.",
   "themeSelect.accessibleLabel": "테마 선택",

package/translations/nb.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Gå til innholdet",
   "search.label": "Søk",
-  "search.shortcutLabel": "(Trykk / for å søke)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Avbryt",
   "search.devWarning": "Søk er bare tilgjengelig i produksjonsbygg. \nPrøv å bygg siden og forhåndsvis den for å teste det lokalt.",
   "themeSelect.accessibleLabel": "Velg tema",
@@ -20,10 +20,10 @@
   "page.nextLink": "Neste",
   "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Siden ble ikke funnet. Sjekk URL-en eller prøv å bruke søkefeltet.",
-  "aside.note": "Note",
-  "aside.tip": "Tip",
-  "aside.caution": "Caution",
-  "aside.danger": "Danger",
-  "fileTree.directory": "Directory",
+  "aside.note": "Merknad",
+  "aside.tip": "Tips",
+  "aside.caution": "Advarsel",
+  "aside.danger": "Fare",
+  "fileTree.directory": "Mappe",
   "builtWithStarlight.label": "Laget med Starlight"
 }

package/translations/nl.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Ga naar inhoud",
   "search.label": "Zoeken",
-  "search.shortcutLabel": "(Druk op / om te zoeken)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Annuleren",
   "search.devWarning": "Zoeken is alleen beschikbaar tijdens productie. \nProbeer om de site te builden en er een preview van te bekijken om lokaal te testen.",
   "themeSelect.accessibleLabel": "Selecteer thema",

package/translations/pl.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Przejdź do głównej zawartości",
   "search.label": "Szukaj",
-  "search.shortcutLabel": "(Naciśnij /, aby wyszukać)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Anuluj",
   "search.devWarning": "Wyszukiwanie jest dostępne tylko w buildach produkcyjnych. \nSpróbuj zbudować i uruchomić aplikację, aby przetestować lokalnie.",
   "themeSelect.accessibleLabel": "Wybierz motyw",

package/translations/pt.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Pular para o conteúdo",
   "search.label": "Pesquisar",
-  "search.shortcutLabel": "(Pressione / para Pesquisar)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Cancelar",
   "search.devWarning": "A pesquisa está disponível apenas em builds em produção. \nTente fazer a build e pré-visualize o site para testar localmente.",
   "themeSelect.accessibleLabel": "Selecionar tema",

package/translations/ro.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Sari la conținut",
   "search.label": "Caută",
-  "search.shortcutLabel": "(Apasă pe / ca să cauți)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Anulează",
   "search.devWarning": "Căutarea este disponibilă numai în versiunea de producție. \nÎncercă să construiești și să previzualizezi site-ul pentru a-l testa local.",
   "themeSelect.accessibleLabel": "Selectează tema",

package/translations/ru.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Перейти к содержимому",
   "search.label": "Поиск",
-  "search.shortcutLabel": "(Нажмите / для поиска)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Отменить",
   "search.devWarning": "Поиск доступен только в производственных сборках. \nПопробуйте выполнить сборку и просмотреть сайт, чтобы протестировать его локально.",
   "themeSelect.accessibleLabel": "Выберите тему",

package/translations/sk.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Preskočiť na obsah",
   "search.label": "Hľadať",
-  "search.shortcutLabel": "(Stlačením / hľadajte)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Zrušiť",
   "search.devWarning": "Vyhľadávanie je dostupné len v produkčných zostaveniach. \nSkúste vytvoriť a zobraziť náhľad stránky lokálne.",
   "themeSelect.accessibleLabel": "Vyberte tému",

package/translations/sv.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Hoppa till innehåll",
   "search.label": "Sök",
-  "search.shortcutLabel": "(Tryck / för att söka)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Avbryt",
   "search.devWarning": "Sökfunktionen är endast tillgänglig i produktionsbyggen. \nProva att bygga och förhandsvisa siten för att testa det lokalt.",
   "themeSelect.accessibleLabel": "Välj tema",

package/translations/tr.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "İçeriğe geç",
   "search.label": "Ara",
-  "search.shortcutLabel": "(Aramak için / bas)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "İptal",
   "search.devWarning": "Arama yalnızca üretim derlemelerinde kullanılabilir. \nYerel bilgisayarınızda test etmek için siteyi derleyin ve önizleme yapın.",
   "themeSelect.accessibleLabel": "Tema seç",

package/translations/uk.json

@@ -1,9 +1,9 @@
 {
   "skipLink.label": "Перейти до вмісту",
   "search.label": "Пошук",
-  "search.shortcutLabel": "(Натисніть / для Пошуку)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Скасувати",
-  "search.devWarning": "Пошук доступний лише у виробничих зборках. \nСпробуйте зібрати та переглянути сайт, щоби протестувати його локально",
+  "search.devWarning": "Пошук доступний лише у виробничих збірках. \nСпробуйте зібрати та переглянути сайт, щоби протестувати його локально",
   "themeSelect.accessibleLabel": "Обрати тему",
   "themeSelect.dark": "Темна",
   "themeSelect.light": "Світла",
@@ -18,12 +18,12 @@
   "page.lastUpdated": "Останнє оновлення:",
   "page.previousLink": "Назад",
   "page.nextLink": "Далі",
-  "page.draft": "This content is a draft and will not be included in production builds.",
+  "page.draft": "Цей контент є чернеткою і не буде включений до виробничих збірок.",
   "404.text": "Сторінку не знайдено. Перевірте URL або спробуйте скористатися пошуком.",
   "aside.note": "Заувага",
   "aside.tip": "Порада",
   "aside.caution": "Обережно",
   "aside.danger": "Небезпечно",
-  "fileTree.directory": "Directory",
-  "builtWithStarlight.label": "Built with Starlight"
+  "fileTree.directory": "Каталог",
+  "builtWithStarlight.label": "Створено з Starlight"
 }

package/translations/vi.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "Bỏ qua nội dung",
   "search.label": "Tìm kiếm",
-  "search.shortcutLabel": "(Nhấn / để Tìm kiếm)",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "Thoát",
   "search.devWarning": "Tìm kiếm không khả dụng khi đang trong môi trường lập trình. \nThử xuất bản website và tìm kiếm.",
   "themeSelect.accessibleLabel": "Chọn giao diện",

package/translations/zh-CN.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "跳转到内容",
   "search.label": "搜索",
-  "search.shortcutLabel": "（按 / 进行搜索）",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "取消",
   "search.devWarning": "搜索仅适用于生产版本。\n尝试构建并预览网站以在本地测试。",
   "themeSelect.accessibleLabel": "选择主题",

package/translations/zh-TW.json

@@ -1,7 +1,7 @@
 {
   "skipLink.label": "跳到內容",
   "search.label": "搜尋",
-  "search.shortcutLabel": "（按 / 鍵開始搜尋）",
+  "search.ctrlKey": "Ctrl",
   "search.cancelLabel": "取消",
   "search.devWarning": "正式版本才能使用搜尋功能。\n如要在本地測試，請先建置並預覽網站。",
   "themeSelect.accessibleLabel": "選擇佈景主題",

package/utils/error-map.ts

@@ -88,7 +88,12 @@ const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 						expectedShape.push(relativePath);
 					}
 				}
-				expectedShapes.push(`{ ${expectedShape.join('; ')} }`);
+				if (expectedShape.length === 1 && !expectedShape[0]?.includes(':')) {
+					// In this case the expected shape is not an object, but probably a literal type, e.g. `['string']`.
+					expectedShapes.push(expectedShape.join(''));
+				} else {
+					expectedShapes.push(`{ ${expectedShape.join('; ')} }`);
+				}
 			}
 			if (expectedShapes.length) {
 				details.push('> Expected type `' + expectedShapes.join(' | ') + '`');

package/utils/navigation.ts

@@ -1,8 +1,10 @@
+import { AstroError } from 'astro/errors';
 import config from 'virtual:starlight/user-config';
 import type { Badge } from '../schemas/badge';
 import type { PrevNextLinkConfig } from '../schemas/prevNextLink';
 import type {
 	AutoSidebarGroup,
+	InternalSidebarLinkItem,
 	LinkHTMLAttributes,
 	SidebarItem,
 	SidebarLinkItem,
@@ -11,7 +13,7 @@ import { createPathFormatter } from './createPathFormatter';
 import { formatPath } from './format-path';
 import { pickLang } from './i18n';
 import { ensureLeadingSlash, ensureTrailingSlash, stripLeadingAndTrailingSlashes } from './path';
-import { getLocaleRoutes, type Route } from './routing';
+import { getLocaleRoutes, routes, type Route } from './routing';
 import { localeToLang, slugToPathname } from './slugs';
 
 const DirKey = Symbol('DirKey');
@@ -70,9 +72,11 @@ function configItemToEntry(
 	routes: Route[]
 ): SidebarEntry {
 	if ('link' in item) {
-		return linkFromConfig(item, locale, currentPathname);
+		return linkFromSidebarLinkItem(item, locale, currentPathname);
 	} else if ('autogenerate' in item) {
 		return groupFromAutogenerateConfig(item, locale, routes, currentPathname);
+	} else if ('slug' in item) {
+		return linkFromInternalSidebarLinkItem(item, locale, currentPathname);
 	} else {
 		return {
 			type: 'group',
@@ -113,8 +117,8 @@ function groupFromAutogenerateConfig(
 /** Check if a string starts with one of `http://` or `https://`. */
 const isAbsolute = (link: string) => /^https?:\/\//.test(link);
 
-/** Create a link entry from a user config object. */
-function linkFromConfig(
+/** Create a link entry from a manual link item in user config. */
+function linkFromSidebarLinkItem(
 	item: SidebarLinkItem,
 	locale: string | undefined,
 	currentPathname: string
@@ -129,6 +133,36 @@ function linkFromConfig(
 	return makeLink(href, label, currentPathname, item.badge, item.attrs);
 }
 
+/** Create a link entry from an automatic internal link item in user config. */
+function linkFromInternalSidebarLinkItem(
+	item: InternalSidebarLinkItem,
+	locale: string | undefined,
+	currentPathname: string
+) {
+	let slugWithLocale = locale ? locale + '/' + item.slug : item.slug;
+	// Astro passes root `index.[md|mdx]` entries with a slug of `index`
+	slugWithLocale = slugWithLocale.replace(/\/?index$/, '');
+	const entry = routes.find((entry) => slugWithLocale === entry.slug);
+	if (!entry) {
+		const hasExternalSlashes = item.slug.at(0) === '/' || item.slug.at(-1) === '/';
+		if (hasExternalSlashes) {
+			throw new AstroError(
+				`The slug \`"${item.slug}"\` specified in the Starlight sidebar config must not start or end with a slash.`,
+				`Please try updating \`"${item.slug}"\` to \`"${stripLeadingAndTrailingSlashes(item.slug)}"\`.`
+			);
+		} else {
+			throw new AstroError(
+				`The slug \`"${item.slug}"\` specified in the Starlight sidebar config does not exist.`,
+				'Update the Starlight config to reference a valid entry slug in the docs content collection.\n' +
+					'Learn more about Astro content collection slugs at https://docs.astro.build/en/reference/api-reference/#getentry'
+			);
+		}
+	}
+	const label =
+		pickLang(item.translations, localeToLang(locale)) || item.label || entry.entry.data.title;
+	return makeLink(entry.slug, label, currentPathname, item.badge, item.attrs);
+}
+
 /** Create a link entry. */
 function makeLink(
 	href: string,