From 4485d90fbddf7c9458b43f9d9b7560b41ec9e98f Mon Sep 17 00:00:00 2001
From: Chris Swithinbank
Date: Fri, 28 Jul 2023 23:12:55 +0200
Subject: Add support for customising sidebar labels from frontmatter (#424)

---
 .changeset/cuddly-vans-shout.md                    | 13 +++++
 docs/src/content/docs/reference/frontmatter.md     | 17 ++++++-
 .../__tests__/basics/navigation-labels.test.ts     | 56 ++++++++++++++++++++++
 packages/starlight/schema.ts                       |  6 +++
 packages/starlight/utils/navigation.ts             |  6 ++-
 5 files changed, 96 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/cuddly-vans-shout.md
 create mode 100644 packages/starlight/__tests__/basics/navigation-labels.test.ts

diff --git a/.changeset/cuddly-vans-shout.md b/.changeset/cuddly-vans-shout.md
new file mode 100644
index 00000000..2341fee9
--- /dev/null
+++ b/.changeset/cuddly-vans-shout.md
@@ -0,0 +1,13 @@
+---
+'@astrojs/starlight': minor
+---
+
+Add support for customising autogenerated sidebar link labels from page frontmatter, overriding the page title:
+
+```md
+---
+title: About this project
+sidebar:
+  label: About
+---
+```
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index f95910c6..d45bbc76 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -191,10 +191,25 @@ next: false
 
 ### `sidebar`
 
-**type:** `{ order?: number }`
+**type:** `{ label?: string; order?: number }`
 
 Control how this page is displayed in the [sidebar](/reference/configuration/#sidebar), when using an autogenerated link group.
 
+#### `label`
+
+**type:** `string`  
+**default:** the page [`title`](#title-required)
+
+Set the label for this page in the sidebar when displayed in an autogenerated group of links.
+
+```md
+---
+title: About this project
+sidebar:
+  label: About
+---
+```
+
 #### `order`
 
 **type:** `number`
diff --git a/packages/starlight/__tests__/basics/navigation-labels.test.ts b/packages/starlight/__tests__/basics/navigation-labels.test.ts
new file mode 100644
index 00000000..eae89687
--- /dev/null
+++ b/packages/starlight/__tests__/basics/navigation-labels.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, test, vi } from 'vitest';
+import { getSidebar } from '../../utils/navigation';
+
+vi.mock('astro:content', async () =>
+	(await import('../test-utils')).mockedAstroContent({
+		docs: [
+			['index.mdx', { title: 'Home Page' }],
+			[
+				'environmental-impact.md',
+				{ title: 'Eco-friendly docs', sidebar: { label: 'Environmental impact' } },
+			],
+			['guides/authoring-content.md', { title: 'Authoring Markdown' }],
+			['guides/components.mdx', { title: 'Using components', sidebar: { label: 'Components' } }],
+		],
+	})
+);
+
+describe('getSidebar', () => {
+	test('returns sidebar entries sorted by frontmatter order', () => {
+		expect(getSidebar('/', undefined)).toMatchInlineSnapshot(`
+			[
+			  {
+			    "href": "/",
+			    "isCurrent": true,
+			    "label": "Home Page",
+			    "type": "link",
+			  },
+			  {
+			    "href": "/environmental-impact/",
+			    "isCurrent": false,
+			    "label": "Environmental impact",
+			    "type": "link",
+			  },
+			  {
+			    "collapsed": false,
+			    "entries": [
+			      {
+			        "href": "/guides/authoring-content/",
+			        "isCurrent": false,
+			        "label": "Authoring Markdown",
+			        "type": "link",
+			      },
+			      {
+			        "href": "/guides/components/",
+			        "isCurrent": false,
+			        "label": "Components",
+			        "type": "link",
+			      },
+			    ],
+			    "label": "guides",
+			    "type": "group",
+			  },
+			]
+		`);
+	});
+});
diff --git a/packages/starlight/schema.ts b/packages/starlight/schema.ts
index 112543cd..b005f955 100644
--- a/packages/starlight/schema.ts
+++ b/packages/starlight/schema.ts
@@ -136,6 +136,12 @@ export function docsSchema() {
 					 * If two pages have the same order value, they will be sorted alphabetically by slug.
 					 */
 					order: z.number().optional(),
+
+					/**
+					 * The label for this page in the navigation.
+					 * Defaults to the page `title` if not set.
+					 */
+					label: z.string().optional(),
 				})
 				.default({}),
 		});
diff --git a/packages/starlight/utils/navigation.ts b/packages/starlight/utils/navigation.ts
index cfc806b8..fc6371a9 100644
--- a/packages/starlight/utils/navigation.ts
+++ b/packages/starlight/utils/navigation.ts
@@ -168,7 +168,11 @@ function treeify(routes: Route[], baseDir: string): Dir {
 
 /** Create a link entry for a given content collection entry. */
 function linkFromRoute(route: Route, currentPathname: string): Link {
-	return makeLink(slugToPathname(route.slug), route.entry.data.title, currentPathname);
+	return makeLink(
+		slugToPathname(route.slug),
+		route.entry.data.sidebar.label || route.entry.data.title,
+		currentPathname
+	);
 }
 
 /**
-- 
cgit