Add support for custom HTML attributes to sidebar links (withastro#774)

Co-authored-by: Chris Swithinbank <[email protected]>
morinokami · Oct 6, 2023 · 903a579 · 903a579
1 parent b7b23a2
commit 903a579
Show file tree

Hide file tree

Showing 21 changed files with 390 additions and 88 deletions.
diff --git a/.changeset/fuzzy-foxes-confess.md b/.changeset/fuzzy-foxes-confess.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Support adding HTML attributes to sidebar links from config and frontmatter
diff --git a/docs/src/components/sidebar-preview.astro b/docs/src/components/sidebar-preview.astro
@@ -1,5 +1,5 @@
 ---
-import type { AutoSidebarGroup, SidebarItem } from '../../../packages/starlight/utils/user-config';
+import type { AutoSidebarGroup, SidebarItem } from '../../../packages/starlight/schemas/sidebar';
 import SidebarSublist from '../../../packages/starlight/components/SidebarSublist.astro';
 import type { SidebarEntry } from '../../../packages/starlight/utils/navigation';
 
@@ -20,11 +20,10 @@ function makeEntries(items: SidebarConfig): SidebarEntry[] {
 				href: item.link,
 				isCurrent: false,
 				badge: item.badge,
+				attrs: item.attrs ?? {},
 			};
 		}
 
-		item;
-
 		return {
 			type: 'group',
 			label: item.label,

diff --git a/docs/src/content/docs/guides/sidebar.mdx b/docs/src/content/docs/guides/sidebar.mdx
@@ -316,6 +316,50 @@ The configuration above generates the following sidebar:
 	]}
 />
 
+## Custom HTML attributes
+
+Links can also include an `attrs` property to add custom HTML attributes to the link element.
+
+In the following example, `attrs` is used to add a `target="_blank"` attribute, so that the link opens in a new tab, and to apply a custom `style` attribute to italicize the link label:
+
+```js
+starlight({
+	sidebar: [
+		{
+			label: 'Guides',
+			items: [
+				// An external link to the Astro docs opening in a new tab.
+				{
+					label: 'Astro Docs',
+					link: 'https://docs.astro.build/',
+					attrs: { target: '_blank', style: 'font-style: italic' },
+				},
+			],
+		},
+	],
+});
+```
+
+The configuration above generates the following sidebar:
+
+<SidebarPreview
+	config={[
+		{
+			label: 'Guides',
+			items: [
+				{
+					label: 'Astro Docs',
+					link: 'https://docs.astro.build/',
+					attrs: {
+						target: '_blank',
+						style: 'font-style: italic',
+					},
+				},
+			],
+		},
+	]}
+/>
+
 ## Internationalization
 
 Use the `translations` property on link and group entries to translate the link or group label for each supported language.

diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
@@ -187,6 +187,7 @@ type SidebarItem = {
   | {
       link: string;
       badge?: string | BadgeConfig;
+      attrs?: Record<string, string | number | boolean | undefined>;
     }
   | { items: SidebarItem[]; collapsed?: boolean }
   | {

diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
@@ -224,10 +224,22 @@ pagefind: false
 
 ### `sidebar`
 
-**type:** `{ label?: string; order?: number; hidden?: boolean; badge?: string | BadgeConfig }`
+**type:** [`SidebarConfig`](#sidebarconfig)
 
 Control how this page is displayed in the [sidebar](/reference/configuration/#sidebar), when using an autogenerated link group.
 
+#### `SidebarConfig`
+
+```ts
+interface SidebarConfig {
+  label?: string;
+  order?: number;
+  hidden?: boolean;
+  badge?: string | BadgeConfig;
+  attrs?: Record<string, string | number | boolean | undefined>;
+}
+```
+
 #### `label`
 
 **type:** `string`  
@@ -299,3 +311,19 @@ sidebar:
     variant: caution
 ---
 ```
+
+#### `attrs`
+
+**type:** `Record<string, string | number | boolean | undefined>`
+
+HTML attributes to add to the page link in the sidebar when displayed in an autogenerated group of links.
+
+```md
+---
+title: Page opening in a new tab
+sidebar:
+  # Opens the page in a new tab
+  attrs:
+    target: _blank
+---
+```
diff --git a/packages/starlight/__tests__/basics/navigation-labels.test.ts b/packages/starlight/__tests__/basics/navigation-labels.test.ts
@@ -20,13 +20,15 @@ describe('getSidebar', () => {
 		expect(getSidebar('/', undefined)).toMatchInlineSnapshot(`
 			[
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/",
 			    "isCurrent": true,
 			    "label": "Home Page",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/environmental-impact/",
 			    "isCurrent": false,
@@ -37,13 +39,15 @@ describe('getSidebar', () => {
 			    "collapsed": false,
 			    "entries": [
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/guides/authoring-content/",
 			        "isCurrent": false,
 			        "label": "Authoring Markdown",
 			        "type": "link",
 			      },
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/guides/components/",
 			        "isCurrent": false,

diff --git a/packages/starlight/__tests__/basics/navigation-order.test.ts b/packages/starlight/__tests__/basics/navigation-order.test.ts
@@ -20,13 +20,15 @@ describe('getSidebar', () => {
 			    "collapsed": false,
 			    "entries": [
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/guides/components/",
 			        "isCurrent": false,
 			        "label": "Components",
 			        "type": "link",
 			      },
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/guides/authoring-content/",
 			        "isCurrent": false,
@@ -38,13 +40,15 @@ describe('getSidebar', () => {
 			    "type": "group",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/environmental-impact/",
 			    "isCurrent": false,
 			    "label": "Eco-friendly docs",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/",
 			    "isCurrent": true,

diff --git a/packages/starlight/__tests__/basics/navigation.test.ts b/packages/starlight/__tests__/basics/navigation.test.ts
@@ -18,13 +18,15 @@ describe('getSidebar', () => {
 		expect(getSidebar('/', undefined)).toMatchInlineSnapshot(`
 			[
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/",
 			    "isCurrent": true,
 			    "label": "Home Page",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/environmental-impact/",
 			    "isCurrent": false,
@@ -35,13 +37,15 @@ describe('getSidebar', () => {
 			    "collapsed": false,
 			    "entries": [
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/guides/authoring-content/",
 			        "isCurrent": false,
 			        "label": "Authoring Markdown",
 			        "type": "link",
 			      },
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/guides/components/",
 			        "isCurrent": false,
@@ -103,27 +107,31 @@ describe('flattenSidebar', () => {
 		expect(flattened).toMatchInlineSnapshot(`
 			[
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/",
 			    "isCurrent": true,
 			    "label": "Home Page",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/environmental-impact/",
 			    "isCurrent": false,
 			    "label": "Eco-friendly docs",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/guides/authoring-content/",
 			    "isCurrent": false,
 			    "label": "Authoring Markdown",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/guides/components/",
 			    "isCurrent": false,
@@ -142,13 +150,15 @@ describe('getPrevNextLinks', () => {
 		expect(links).toMatchInlineSnapshot(`
 			{
 			  "next": {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/guides/authoring-content/",
 			    "isCurrent": false,
 			    "label": "Authoring Markdown",
 			    "type": "link",
 			  },
 			  "prev": {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/",
 			    "isCurrent": false,
@@ -235,6 +245,7 @@ describe('getPrevNextLinks', () => {
 			href: '/x/',
 			label: 'X',
 			isCurrent: false,
+			attrs: {},
 		});
 	});
 

diff --git a/packages/starlight/__tests__/i18n/navigation-order.test.ts b/packages/starlight/__tests__/i18n/navigation-order.test.ts
@@ -30,13 +30,15 @@ describe('getSidebar', () => {
 		expect(getSidebar('/en/', 'en')).toMatchInlineSnapshot(`
 			[
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/en/",
 			    "isCurrent": true,
 			    "label": "Home page",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/en/404/",
 			    "isCurrent": false,
@@ -47,6 +49,7 @@ describe('getSidebar', () => {
 			    "collapsed": false,
 			    "entries": [
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/en/guides/authoring-content/",
 			        "isCurrent": false,
@@ -65,13 +68,15 @@ describe('getSidebar', () => {
 		expect(getSidebar('/fr/', 'fr')).toMatchInlineSnapshot(`
 			[
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/fr/",
 			    "isCurrent": true,
 			    "label": "Accueil",
 			    "type": "link",
 			  },
 			  {
+			    "attrs": {},
 			    "badge": undefined,
 			    "href": "/fr/404/",
 			    "isCurrent": false,
@@ -82,6 +87,7 @@ describe('getSidebar', () => {
 			    "collapsed": false,
 			    "entries": [
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/fr/guides/authoring-content/",
 			        "isCurrent": false,
@@ -96,13 +102,15 @@ describe('getSidebar', () => {
 			    "collapsed": false,
 			    "entries": [
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/fr/référence/bénéfice/",
 			        "isCurrent": false,
 			        "label": "Bénéfice",
 			        "type": "link",
 			      },
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/fr/référence/bricolage/",
 			        "isCurrent": false,
@@ -117,13 +125,15 @@ describe('getSidebar', () => {
 			    "collapsed": false,
 			    "entries": [
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/fr/route/décoder/",
 			        "isCurrent": false,
 			        "label": "Décoder",
 			        "type": "link",
 			      },
 			      {
+			        "attrs": {},
 			        "badge": undefined,
 			        "href": "/fr/route/distribuer/",
 			        "isCurrent": false,