Feat: Autogenerate sidebar labels (#1874)

Co-authored-by: Chris Swithinbank <[email protected]>
withastro · Jul 5, 2024 · eeba06e · eeba06e
1 parent 48ce125
commit eeba06e
Show file tree

Hide file tree

Showing 17 changed files with 742 additions and 102 deletions.
diff --git a/.changeset/seven-owls-taste.md b/.changeset/seven-owls-taste.md
@@ -0,0 +1,19 @@
+---
+'@astrojs/starlight': patch
+---
+
+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.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -87,49 +87,11 @@ export default defineConfig({
 						uk: 'Почніть звідси',
 					},
 					items: [
-						{
-							label: 'Getting Started',
-							link: 'getting-started',
-							translations: {
-								de: 'Erste Schritte',
-								es: 'Empezando',
-								ja: '入門',
-								fr: 'Mise en route',
-								it: 'Iniziamo',
-								id: 'Memulai',
-								'zh-CN': '开始使用',
-								'pt-BR': 'Introdução',
-								'pt-PT': 'Introdução',
-								ko: '시작하기',
-								tr: 'Başlarken',
-								ru: 'Введение',
-								hi: 'पहले कदम',
-								uk: 'Вступ',
-							},
-						},
-						{
-							label: 'Manual Setup',
-							link: 'manual-setup',
-							translations: {
-								de: 'Manuelle Einrichtung',
-								es: 'Configuración Manual',
-								ja: '手動セットアップ',
-								fr: 'Installation manuelle',
-								// it: 'Manual Setup',
-								id: 'Instalasi Manual',
-								'zh-CN': '手动配置',
-								'pt-BR': 'Instalação Manual',
-								'pt-PT': 'Instalação Manual',
-								ko: '수동으로 설정하기',
-								tr: 'Elle Kurulum',
-								ru: 'Установка вручную',
-								hi: 'मैनुअल सेटअप',
-								uk: 'Ручне встановлення',
-							},
-						},
+						'getting-started',
+						'manual-setup',
 						{
 							label: 'Environmental Impact',
-							link: 'environmental-impact',
+							slug: 'environmental-impact',
 							translations: {
 								de: 'Umweltbelastung',
 								es: 'Documentación ecológica',

diff --git a/docs/src/components/sidebar-preview.astro b/docs/src/components/sidebar-preview.astro
@@ -1,13 +1,17 @@
 ---
-import type { AutoSidebarGroup, SidebarItem } from '../../../packages/starlight/schemas/sidebar';
+import type {
+	AutoSidebarGroup,
+	SidebarItem,
+	InternalSidebarLinkItem,
+} from '../../../packages/starlight/schemas/sidebar';
 import SidebarSublist from '../../../packages/starlight/components/SidebarSublist.astro';
 import type { SidebarEntry } from '../../../packages/starlight/utils/navigation';
 
 interface Props {
 	config: SidebarConfig;
 }
 
-type SidebarConfig = Exclude<SidebarItem, AutoSidebarGroup>[];
+type SidebarConfig = Exclude<SidebarItem, AutoSidebarGroup | InternalSidebarLinkItem>[];
 
 const { config } = Astro.props;
 

diff --git a/docs/src/content/docs/guides/sidebar.mdx b/docs/src/content/docs/guides/sidebar.mdx
@@ -49,19 +49,73 @@ Learn more about autogenerated sidebars in the [autogenerated groups](#autogener
 
 ## Add links and link groups
 
-To configure your sidebar [links](#links) and [groups of links](#groups) (within a collapsible header), use the [`starlight.sidebar`](/reference/configuration/#sidebar) property in `astro.config.mjs`.
+To configure your sidebar links and groups of links (within a collapsible header), use the [`starlight.sidebar`](/reference/configuration/#sidebar) property in `astro.config.mjs`.
 
 By combining links and groups, you can create a wide variety of sidebar layouts.
 
-### Links
+### Internal links
 
-Add a link to an internal or external page using an object with `label` and `link` properties.
+Add a link to a page in `src/content/docs/` using an object with the `slug` property.
+The linked page’s title will be used as the label by default.
+
+For example, with the following configuration:
+
+```js "slug:"
+starlight({
+	sidebar: [
+		{ slug: 'constellations/andromeda' },
+		{ slug: 'constellations/orion' },
+	],
+});
+```
+
+And the following file structure:
+
+<FileTree>
+
+- src/
+  - content/
+    - docs/
+      - constellations/
+        - andromeda.md
+        - orion.md
+
+</FileTree>
+
+The following sidebar will be generated:
+
+<SidebarPreview
+	config={[
+		{ label: 'Andromeda', link: '' },
+		{ label: 'Orion', link: '' },
+	]}
+/>
+
+To override the values inferred from a linked page’s frontmatter, you can add `label`, [`translations`](#internationalization), and [`attrs`](#custom-html-attributes) properties.
+
+See [“Customizing autogenerated links”](#customizing-autogenerated-links-in-frontmatter) for more details about controlling the sidebar appearance from page frontmatter.
+
+#### Shorthand for internal links
+
+Internal links can also be specified by providing only a string for the page slug as a shorthand.
+
+For example, the following configuration is equivalent to the configuration above, which used `slug`:
+
+```js "slug:"
+starlight({
+	sidebar: ['constellations/andromeda', 'constellations/orion'],
+});
+```
+
+### Other links
+
+Add a link to an external or non-docs page using an object with `label` and `link` properties.
 
 ```js "label:" "link:"
 starlight({
 	sidebar: [
-		// A link to the Ganymede moon page.
-		{ label: 'Ganymede', link: '/moons/ganymede/' },
+		// A link to a non-docs page on this site.
+		{ label: 'Meteor Store', link: '/shop/' },
 		// An external link to the NASA website.
 		{ label: 'NASA', link: 'https://www.nasa.gov/' },
 	],
@@ -72,7 +126,7 @@ The configuration above generates the following sidebar:
 
 <SidebarPreview
 	config={[
-		{ label: 'Ganymede', link: '' },
+		{ label: 'Meteor Store', link: '' },
 		{ label: 'NASA', link: 'https://www.nasa.gov/' },
 	]}
 />
@@ -93,15 +147,15 @@ starlight({
 		{
 			label: 'Constellations',
 			items: [
-				{ label: 'Carina', link: '/constellations/carina/' },
-				{ label: 'Centaurus', link: '/constellations/centaurus/' },
+				'constellations/carina',
+				'constellations/centaurus',
 				// A nested group of links for seasonal constellations.
 				{
 					label: 'Seasonal',
 					items: [
-						{ label: 'Andromeda', link: '/constellations/andromeda/' },
-						{ label: 'Orion', link: '/constellations/orion/' },
-						{ label: 'Ursa Minor', link: '/constellations/ursa-minor/' },
+						'constellations/andromeda',
+						'constellations/orion',
+						'constellations/ursa-minor',
 					],
 				},
 			],
@@ -186,7 +240,7 @@ The following sidebar will be generated:
 	]}
 />
 
-#### Customizing autogenerated links in frontmatter
+## Customizing autogenerated links in frontmatter
 
 Use the [`sidebar` frontmatter field](/reference/frontmatter/#sidebar) in individual pages to customize autogenerated links.
 
@@ -228,23 +282,22 @@ An autogenerated group including a page with the frontmatter above will generate
 />
 
 :::note
-The `sidebar` frontmatter configuration is only used for autogenerated links and will be ignored for manually defined links.
+The `sidebar` frontmatter configuration is only used for links in autogenerated groups and docs links defined with the `slug` property. It does not apply to links defined with the `link` property.
 :::
 
 ## Badges
 
 Links, groups, and autogenerated groups can also include a `badge` property to display a badge next to their label.
 
-```js {10,17}
+```js {9,16}
 starlight({
 	sidebar: [
 		{
 			label: 'Stars',
 			items: [
 				// A link with a "Supergiant" badge.
 				{
-					label: 'Persei',
-					link: '/stars/persei/',
+					slug: 'stars/persei',
 					badge: 'Supergiant',
 				},
 			],
@@ -303,16 +356,15 @@ By default, the badge will use the accent color of your site. To use a built-in
 
 Optionally, you can create a custom badge style by setting the `class` property to a CSS class name.
 
-```js {10}
+```js {9}
 starlight({
 	sidebar: [
 		{
 			label: 'Stars',
 			items: [
 				// A link with a yellow "Stub" badge.
 				{
-					label: 'Sirius',
-					link: '/stars/sirius/',
+					slug: 'stars/sirius',
 					badge: { text: 'Stub', variant: 'caution' },
 				},
 			],
@@ -401,14 +453,14 @@ starlight({
 					translations: {
 						'pt-BR': 'Andrômeda',
 					},
-					link: '/constellations/andromeda/',
+					slug: 'constellations/andromeda',
 				},
 				{
 					label: 'Scorpius',
 					translations: {
 						'pt-BR': 'Escorpião',
 					},
-					link: '/constellations/scorpius/',
+					slug: 'constellations/scorpius',
 				},
 			],
 		},
@@ -430,6 +482,44 @@ Browsing the documentation in Brazilian Portuguese will generate the following s
 	]}
 />
 
+### Internationalization with internal links
+
+[Internal links](#internal-links) will automatically use translated page titles from content frontmatter by default:
+
+```js {9-10}
+starlight({
+	sidebar: [
+		{
+			label: 'Constellations',
+			translations: {
+				'pt-BR': 'Constelações',
+			},
+			items: [
+				{ slug: 'constellations/andromeda' },
+				{ slug: 'constellations/scorpius' },
+			],
+		},
+	],
+});
+```
+
+Browsing the documentation in Brazilian Portuguese will generate the following sidebar:
+
+<SidebarPreview
+	config={[
+		{
+			label: 'Constelações',
+			items: [
+				{ label: 'Andrômeda', link: '' },
+				{ label: 'Escorpião', link: '' },
+			],
+		},
+	]}
+/>
+
+In multilingual sites, the value of `slug` does not include the language portion of the URL.
+For example, if you have pages at `en/intro` and `pt-br/intro`, the slug is `intro` when configuring the sidebar.
+
 ## Collapsing groups
 
 Groups of links can be collapsed by default by setting the `collapsed` property to `true`.
@@ -441,10 +531,7 @@ starlight({
 			label: 'Constellations',
 			// Collapse the group by default.
 			collapsed: true,
-			items: [
-				{ label: 'Andromeda', link: '/constellations/andromeda/' },
-				{ label: 'Orion', link: '/constellations/orion/' },
-			],
+			items: ['constellations/andromeda', 'constellations/orion'],
 		},
 	],
 });