fix: handle build.format links in sidebar

.changeset/sharp-tables-march.md

@@ -0,0 +1,25 @@
+---
+'@astrojs/starlight': minor
+---
+
+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({
+      // ...
+    }),
+  ],
+});
+```

docs/astro.config.mjs

@@ -26,6 +26,7 @@ const site = VERCEL_PREVIEW_SITE || 'https://starlight.astro.build/';
 
 export default defineConfig({
 	site,
+	trailingSlash: 'always',
 	integrations: [
 		starlight({
 			title: 'Starlight',

packages/starlight/__tests__/basics/base.test.ts

@@ -28,8 +28,8 @@ describe('pathWithBase()', () => {
 		test('does not prepend anything', () => {
 			expect(pathWithBase('/path/')).toBe('/path/');
 		});
-		test('adds leading and trailing slashes if needed', () => {
-			expect(pathWithBase('path')).toBe('/path/');
+		test('adds leading slash if needed', () => {
+			expect(pathWithBase('path')).toBe('/path');
 		});
 	});
 

packages/starlight/__tests__/basics/format-path.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'vitest';
+import { createPathFormatter } from '../../utils/createPathFormatter';
+
+type FormatPathOptions = Parameters<typeof createPathFormatter>[0];
+const formatPath = (href: string, opts: FormatPathOptions) => createPathFormatter(opts)(href);
+
+describe.each<{ options: FormatPathOptions; tests: Array<{ path: string; expected: string }> }>([
+	{
+		options: { format: 'file', trailingSlash: 'ignore' },
+		tests: [
+			// index page
+			{ path: '/', expected: '/index.html' },
+			// with trailing slash
+			{ path: '/reference/configuration/', expected: '/reference/configuration.html' },
+			// without trailing slash
+			{ path: '/api/v1/users', expected: '/api/v1/users.html' },
+			// with file extension
+			{ path: '/guides/components.html', expected: '/guides/components.html' },
+			// with file extension and trailing slash
+			{ path: '/guides/components.html/', expected: '/guides/components.html' },
+		],
+	},
+	{
+		options: { format: 'file', trailingSlash: 'always' },
+		tests: [
+			// index page
+			{ path: '/', expected: '/index.html' },
+			// with trailing slash
+			{ path: '/reference/configuration/', expected: '/reference/configuration.html' },
+			// without trailing slash
+			{ path: '/api/v1/users', expected: '/api/v1/users.html' },
+			// with file extension
+			{ path: '/guides/components.html', expected: '/guides/components.html' },
+			// with file extension and trailing slash
+			{ path: '/guides/components.html/', expected: '/guides/components.html' },
+		],
+	},
+	{
+		options: { format: 'file', trailingSlash: 'never' },
+		tests: [
+			// index page
+			{ path: '/', expected: '/index.html' },
+			// with trailing slash
+			{ path: '/reference/configuration/', expected: '/reference/configuration.html' },
+			// without trailing slash
+			{ path: '/api/v1/users', expected: '/api/v1/users.html' },
+			// with file extension
+			{ path: '/guides/components.html', expected: '/guides/components.html' },
+			// with file extension and trailing slash
+			{ path: '/guides/components.html/', expected: '/guides/components.html' },
+		],
+	},
+	{
+		options: { format: 'directory', trailingSlash: 'always' },
+		tests: [
+			// index page
+			{ path: '/', expected: '/' },
+			// with trailing slash
+			{ path: '/reference/configuration/', expected: '/reference/configuration/' },
+			// without trailing slash
+			{ path: '/api/v1/users', expected: '/api/v1/users/' },
+			// with file extension
+			{ path: '/guides/components.html', expected: '/guides/components/' },
+			// with file extension and trailing slash
+			{ path: '/guides/components.html/', expected: '/guides/components/' },
+		],
+	},
+	{
+		options: { format: 'directory', trailingSlash: 'never' },
+		tests: [
+			// index page
+			{ path: '/', expected: '/' },
+			// with trailing slash
+			{ path: '/reference/configuration/', expected: '/reference/configuration' },
+			// without trailing slash
+			{ path: '/api/v1/users', expected: '/api/v1/users' },
+			// with file extension
+			{ path: '/guides/components.html', expected: '/guides/components' },
+			// with file extension and trailing slash
+			{ path: '/guides/components.html/', expected: '/guides/components' },
+		],
+	},
+	{
+		options: { format: 'directory', trailingSlash: 'ignore' },
+		tests: [
+			// index page
+			{ path: '/', expected: '/' },
+			// with trailing slash
+			{ path: '/reference/configuration/', expected: '/reference/configuration/' },
+			// without trailing slash
+			{ path: '/api/v1/users', expected: '/api/v1/users' },
+			// with file extension
+			{ path: '/guides/components.html', expected: '/guides/components' },
+			// with file extension and trailing slash
+			{ path: '/guides/components.html/', expected: '/guides/components' },
+		],
+	},
+])(
+	'formatPath() with { format: $options.format, trailingSlash: $options.trailingSlash }',
+	({ options, tests }) => {
+		test.each(tests)('returns $expected for $path', ({ path, expected }) => {
+			expect(formatPath(path, options)).toBe(expected);
+		});
+	}
+);

packages/starlight/__tests__/basics/navigation.test.ts

@@ -61,23 +61,34 @@ describe('getSidebar', () => {
 		`);
 	});
 
-	test('marks current path with isCurrent', () => {
-		const paths = ['/', '/environmental-impact/', '/guides/authoring-content/'];
-		for (const currentPath of paths) {
+	test.each(['/', '/environmental-impact/', '/guides/authoring-content/'])(
+		'marks current path with isCurrent: %s',
+		(currentPath) => {
 			const items = flattenSidebar(getSidebar(currentPath, undefined));
 			const currentItems = items.filter((item) => item.type === 'link' && item.isCurrent);
 			expect(currentItems).toHaveLength(1);
 			const currentItem = currentItems[0];
 			if (currentItem?.type !== 'link') throw new Error('Expected current item to be link');
 			expect(currentItem.href).toBe(currentPath);
 		}
-	});
+	);
 
 	test('ignore trailing slashes when marking current path with isCurrent', () => {
-		const pathWithoutTrailingSlash = '/environmental-impact';
-		const items = flattenSidebar(getSidebar(pathWithoutTrailingSlash, undefined));
+		const pathWithTrailingSlash = '/environmental-impact/';
+		const items = flattenSidebar(getSidebar(pathWithTrailingSlash, undefined));
 		const currentItems = items.filter((item) => item.type === 'link' && item.isCurrent);
-		expect(currentItems).toMatchObject([{ href: `${pathWithoutTrailingSlash}/`, type: 'link' }]);
+		expect(currentItems).toMatchInlineSnapshot(`
+			[
+			  {
+			    "attrs": {},
+			    "badge": undefined,
+			    "href": "/environmental-impact/",
+			    "isCurrent": true,
+			    "label": "Eco-friendly docs",
+			    "type": "link",
+			  },
+			]
+		`);
 	});
 
 	test('nests files in subdirectory in group when autogenerating', () => {
@@ -243,7 +254,7 @@ describe('getPrevNextLinks', () => {
 		expect(withDefaults.prev).toBeUndefined();
 		expect(withCustomLinks.prev).toEqual({
 			type: 'link',
-			href: '/x/',
+			href: '/x',
 			label: 'X',
 			isCurrent: false,
 			attrs: {},

packages/starlight/__tests__/build-format-file/navigation.ts

@@ -0,0 +1,125 @@
+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' }],
+			['reference/configuration.mdx', { title: 'Config Reference' }],
+			['reference/frontmatter.md', { title: 'Frontmatter Reference' }],
+			// @ts-expect-error — Using a slug not present in Starlight docs site
+			['api/v1/users.md', { title: 'Users API' }],
+			['guides/components.mdx', { title: 'Components' }],
+		],
+	})
+);
+
+describe('getSidebar with build.format = "file"', () => {
+	test('returns an array of sidebar entries with its file extension', () => {
+		expect(getSidebar('/', undefined)).toMatchInlineSnapshot(`
+			[
+			  {
+			    "attrs": {},
+			    "badge": undefined,
+			    "href": "/index.html",
+			    "isCurrent": true,
+			    "label": "Home",
+			    "type": "link",
+			  },
+			  {
+			    "badge": undefined,
+			    "collapsed": false,
+			    "entries": [
+			      {
+			        "attrs": {},
+			        "badge": {
+			          "text": "New",
+			          "variant": "success",
+			        },
+			        "href": "/intro.html",
+			        "isCurrent": false,
+			        "label": "Introduction",
+			        "type": "link",
+			      },
+			      {
+			        "attrs": {},
+			        "badge": {
+			          "text": "Deprecated",
+			          "variant": "default",
+			        },
+			        "href": "/next-steps.html",
+			        "isCurrent": false,
+			        "label": "Next Steps",
+			        "type": "link",
+			      },
+			      {
+			        "attrs": {
+			          "class": "showcase-link",
+			          "target": "_blank",
+			        },
+			        "badge": undefined,
+			        "href": "/showcase.html",
+			        "isCurrent": false,
+			        "label": "Showcase",
+			        "type": "link",
+			      },
+			      {
+			        "attrs": {},
+			        "badge": undefined,
+			        "href": "https://astro.build/",
+			        "isCurrent": false,
+			        "label": "Astro",
+			        "type": "link",
+			      },
+			    ],
+			    "label": "Start Here",
+			    "type": "group",
+			  },
+			  {
+			    "badge": {
+			      "text": "Experimental",
+			      "variant": "default",
+			    },
+			    "collapsed": false,
+			    "entries": [
+			      {
+			        "attrs": {},
+			        "badge": undefined,
+			        "href": "/reference/configuration.html",
+			        "isCurrent": false,
+			        "label": "Config Reference",
+			        "type": "link",
+			      },
+			      {
+			        "attrs": {},
+			        "badge": undefined,
+			        "href": "/reference/frontmatter.html",
+			        "isCurrent": false,
+			        "label": "Frontmatter Reference",
+			        "type": "link",
+			      },
+			    ],
+			    "label": "Reference",
+			    "type": "group",
+			  },
+			  {
+			    "badge": undefined,
+			    "collapsed": false,
+			    "entries": [
+			      {
+			        "attrs": {},
+			        "badge": undefined,
+			        "href": "/api/v1/users.html",
+			        "isCurrent": false,
+			        "label": "Users API",
+			        "type": "link",
+			      },
+			    ],
+			    "label": "API v1",
+			    "type": "group",
+			  },
+			]
+		`);
+	});
+});

packages/starlight/__tests__/build-format-file/vitest.config.ts

@@ -0,0 +1,51 @@
+import { defineVitestConfig } from '../test-config';
+
+export default defineVitestConfig(
+	{
+		title: 'Sidebar Test',
+		sidebar: [
+			// A single link item labelled “Home”.
+			{ label: 'Home', link: '/' },
+			// A group labelled “Start Here” containing two links.
+			{
+				label: 'Start Here',
+				items: [
+					{
+						label: 'Introduction',
+						link: '/intro',
+						badge: {
+							variant: 'success',
+							text: 'New',
+						},
+					},
+					{ label: 'Next Steps', link: '/next-steps', badge: 'Deprecated' },
+					{
+						label: 'Showcase',
+						link: '/showcase',
+						attrs: { class: 'showcase-link', target: '_blank' },
+					},
+					{
+						label: 'Astro',
+						link: 'https://astro.build/',
+					},
+				],
+			},
+			// A group linking to all pages in the reference directory.
+			{
+				label: 'Reference',
+				badge: 'Experimental',
+				autogenerate: { directory: 'reference' },
+			},
+			// A group linking to all pages in the api/v1 directory.
+			{
+				label: 'API v1',
+				autogenerate: { directory: '/api/v1/' },
+			},
+		],
+	},
+	{
+		build: {
+			format: 'file',
+		},
+	}
+);