From 36715edfeb50bfd6f078bb0a16d7a585b62185ad Mon Sep 17 00:00:00 2001
From: HiDeoo <494699+HiDeoo@users.noreply.github.com>
Date: Mon, 15 Apr 2024 10:40:36 +0200
Subject: [PATCH] docs: rewrite `guides/sidebar` examples to be more generic
 (#1751)

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>
Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
---
 docs/src/components/sidebar-preview.astro |   5 +-
 docs/src/content/docs/guides/sidebar.mdx  | 242 +++++++++++-----------
 2 files changed, 121 insertions(+), 126 deletions(-)

diff --git a/docs/src/components/sidebar-preview.astro b/docs/src/components/sidebar-preview.astro
index bd10705d169..f392972a009 100644
--- a/docs/src/components/sidebar-preview.astro
+++ b/docs/src/components/sidebar-preview.astro
@@ -17,7 +17,10 @@ function makeEntries(items: SidebarConfig): SidebarEntry[] {
 			return {
 				type: 'link',
 				label: item.label,
-				href: item.link,
+				// Empty hrefs are used to represent internal links that do not exist in the Starlight
+				// docs. Using a non-existing anchor link like `#_` will not trigger a page reload or any
+				// scrolling.
+				href: item.link.length > 0 ? item.link : '#_',
 				isCurrent: false,
 				badge: item.badge,
 				attrs: item.attrs ?? {},
diff --git a/docs/src/content/docs/guides/sidebar.mdx b/docs/src/content/docs/guides/sidebar.mdx
index 726e9f9a276..bf9d3605642 100644
--- a/docs/src/content/docs/guides/sidebar.mdx
+++ b/docs/src/content/docs/guides/sidebar.mdx
@@ -19,11 +19,11 @@ For example, given the following file structure:
 - src/
   - content/
     - docs/
-      - guides/
-        - components.md
-        - i18n.md
-      - reference/
-        - configuration.md
+      - constellations/
+        - andromeda.md
+        - orion.md
+      - stars/
+        - betelgeuse.md
 
 </FileTree>
 
@@ -32,17 +32,15 @@ The following sidebar will be automatically generated:
 <SidebarPreview
 	config={[
 		{
-			label: 'guides',
+			label: 'constellations',
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
+				{ label: 'Andromeda', link: '' },
+				{ label: 'Orion', link: '' },
 			],
 		},
 		{
-			label: 'reference',
-			items: [
-				{ label: 'Configuration Reference', link: '/reference/configuration/' },
-			],
+			label: 'stars',
+			items: [{ label: 'Betelgeuse', link: '' }],
 		},
 	]}
 />
@@ -62,10 +60,10 @@ Add a link to an internal or external page using an object with `label` and `lin
 ```js "label:" "link:"
 starlight({
 	sidebar: [
-		// A link to the CSS & Styling guide.
-		{ label: 'CSS & Styling', link: '/guides/css-and-tailwind/' },
-		// An external link to the Astro website.
-		{ label: 'Astro', link: 'https://astro.build/' },
+		// A link to the Ganymede moon page.
+		{ label: 'Ganymede', link: '/moons/ganymede/' },
+		// An external link to the NASA website.
+		{ label: 'NASA', link: 'https://www.nasa.gov/' },
 	],
 });
 ```
@@ -74,8 +72,8 @@ The configuration above generates the following sidebar:
 
 <SidebarPreview
 	config={[
-		{ label: 'CSS & Styling', link: '/guides/css-and-tailwind/' },
-		{ label: 'Astro', link: 'https://astro.build/' },
+		{ label: 'Ganymede', link: '' },
+		{ label: 'NASA', link: 'https://www.nasa.gov/' },
 	]}
 />
 
@@ -91,19 +89,19 @@ Add links or subgroups to the `items` array.
 ```js /^\s*(label:|items:)/
 starlight({
 	sidebar: [
-		// A group of links labelled "Guides".
+		// A group of links labelled "Constellations".
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
-				// A nested group of links.
+				{ label: 'Carina', link: '/constellations/carina/' },
+				{ label: 'Centaurus', link: '/constellations/centaurus/' },
+				// A nested group of links for seasonal constellations.
 				{
-					label: 'Styling',
+					label: 'Seasonal',
 					items: [
-						{ label: 'CSS', link: '/guides/css-and-tailwind/' },
-						{ label: 'Tailwind', link: '/guides/css-and-tailwind/' },
-						{ label: 'Shiki', link: '/guides/css-and-tailwind/' },
+						{ label: 'Andromeda', link: '/constellations/andromeda/' },
+						{ label: 'Orion', link: '/constellations/orion/' },
+						{ label: 'Ursa Minor', link: '/constellations/ursa-minor/' },
 					],
 				},
 			],
@@ -117,16 +115,16 @@ The configuration above generates the following sidebar:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
+				{ label: 'Carina', link: '' },
+				{ label: 'Centaurus', link: '' },
 				{
-					label: 'Styling',
+					label: 'Seasonal',
 					items: [
-						{ label: 'CSS', link: '/guides/css-and-tailwind/' },
-						{ label: 'Tailwind', link: '/guides/css-and-tailwind/' },
-						{ label: 'Shiki', link: '/guides/css-and-tailwind/' },
+						{ label: 'Andromeda', link: '' },
+						{ label: 'Orion', link: '' },
+						{ label: 'Ursa Minor', link: '' },
 					],
 				},
 			],
@@ -147,9 +145,9 @@ Add an autogenerated group using an object with `label` and `autogenerate` prope
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
-			// Autogenerate a group of links for the 'guides' directory.
-			autogenerate: { directory: 'guides' },
+			label: 'Constellations',
+			// Autogenerate a group of links for the 'constellations' directory.
+			autogenerate: { directory: 'constellations' },
 		},
 	],
 });
@@ -162,11 +160,11 @@ And the following file structure:
 - src/
   - content/
     - docs/
-      - guides/
-        - components.md
-        - i18n.md
-        - advanced/
-          - project-structure.md
+      - constellations/
+        - carina.md
+        - centaurus.md
+        - seasonal/
+          - andromeda.md
 
 </FileTree>
 
@@ -175,15 +173,13 @@ The following sidebar will be generated:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
+				{ label: 'Carina', link: '' },
+				{ label: 'Centaurus', link: '' },
 				{
-					label: 'advanced',
-					items: [
-						{ label: 'Project Structure', link: '/guides/project-structure/' },
-					],
+					label: 'seasonal',
+					items: [{ label: 'Andromeda', link: '' }],
 				},
 			],
 		},
@@ -219,13 +215,13 @@ An autogenerated group including a page with the frontmatter above will generate
 		{
 			label: 'Guides',
 			items: [
-				{ label: 'A page', link: '#' },
+				{ label: 'A page', link: '' },
 				{
 					label: 'Custom sidebar label',
-					link: '#',
+					link: '',
 					badge: { text: 'New', variant: 'tip' },
 				},
-				{ label: 'Another page', link: '#' },
+				{ label: 'Another page', link: '' },
 			],
 		},
 	]}
@@ -243,21 +239,21 @@ Links, groups, and autogenerated groups can also include a `badge` property to d
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
+			label: 'Stars',
 			items: [
-				// A link with a "New" badge.
+				// A link with a "Supergiant" badge.
 				{
-					label: 'Components',
-					link: '/guides/components/',
-					badge: 'New',
+					label: 'Persei',
+					link: '/stars/persei/',
+					badge: 'Supergiant',
 				},
 			],
 		},
-		// An autogenerated group with a "Deprecated" badge.
+		// An autogenerated group with an "Outdated" badge.
 		{
-			label: 'Reference',
-			badge: 'Deprecated',
-			autogenerate: { directory: 'reference' },
+			label: 'Moons',
+			badge: 'Outdated',
+			autogenerate: { directory: 'moons' },
 		},
 	],
 });
@@ -268,30 +264,30 @@ The configuration above generates the following sidebar:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Stars',
 			items: [
 				{
-					label: 'Components',
-					link: '/guides/components/',
-					badge: { text: 'New', variant: 'default' },
+					label: 'Persei',
+					link: '',
+					badge: { text: 'Supergiant', variant: 'default' },
 				},
 			],
 		},
 		{
-			label: 'Reference',
-			badge: { text: 'Deprecated', variant: 'default' },
+			label: 'Moons',
+			badge: { text: 'Outdated', variant: 'default' },
 			items: [
 				{
-					label: 'Configuration Reference',
-					link: '/reference/configuration/',
+					label: 'Io',
+					link: '',
 				},
 				{
-					label: 'Frontmatter Reference',
-					link: '/reference/frontmatter/',
+					label: 'Europa',
+					link: '',
 				},
 				{
-					label: 'Overrides Reference',
-					link: '/reference/overrides/',
+					label: 'Ganymede',
+					link: '',
 				},
 			],
 		},
@@ -309,13 +305,13 @@ Override the `default` styling, which uses the accent color of your site, by set
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
+			label: 'Stars',
 			items: [
-				// A link with a yellow "Experimental" badge.
+				// A link with a yellow "Stub" badge.
 				{
-					label: 'Components',
-					link: '/guides/components/',
-					badge: { text: 'Experimental', variant: 'caution' },
+					label: 'Sirius',
+					link: '/stars/sirius/',
+					badge: { text: 'Stub', variant: 'caution' },
 				},
 			],
 		},
@@ -328,12 +324,12 @@ The configuration above generates the following sidebar:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Stars',
 			items: [
 				{
-					label: 'Components',
-					link: '/guides/components/',
-					badge: { text: 'Experimental', variant: 'caution' },
+					label: 'Sirius',
+					link: '',
+					badge: { text: 'Stub', variant: 'caution' },
 				},
 			],
 		},
@@ -350,12 +346,12 @@ In the following example, `attrs` is used to add a `target="_blank"` attribute,
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
+			label: 'Resources',
 			items: [
-				// An external link to the Astro docs opening in a new tab.
+				// An external link to the NASA website opening in a new tab.
 				{
-					label: 'Astro Docs',
-					link: 'https://docs.astro.build/',
+					label: 'NASA',
+					link: 'https://www.nasa.gov/',
 					attrs: { target: '_blank', style: 'font-style: italic' },
 				},
 			],
@@ -369,11 +365,11 @@ The configuration above generates the following sidebar:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Resources',
 			items: [
 				{
-					label: 'Astro Docs',
-					link: 'https://docs.astro.build/',
+					label: 'NASA',
+					link: 'https://www.nasa.gov/',
 					attrs: {
 						target: '_blank',
 						style: 'font-style: italic',
@@ -393,24 +389,24 @@ The `label` property will be used for the default locale and for languages witho
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			translations: {
-				'pt-BR': 'Guias',
+				'pt-BR': 'Constelações',
 			},
 			items: [
 				{
-					label: 'Components',
+					label: 'Andromeda',
 					translations: {
-						'pt-BR': 'Componentes',
+						'pt-BR': 'Andrômeda',
 					},
-					link: '/guides/components/',
+					link: '/constellations/andromeda/',
 				},
 				{
-					label: 'Internationalization (i18n)',
+					label: 'Scorpius',
 					translations: {
-						'pt-BR': 'Internacionalização (i18n)',
+						'pt-BR': 'Escorpião',
 					},
-					link: '/guides/i18n/',
+					link: '/constellations/scorpius/',
 				},
 			],
 		},
@@ -423,10 +419,10 @@ Browsing the documentation in Brazilian Portuguese will generate the following s
 <SidebarPreview
 	config={[
 		{
-			label: 'Guias',
+			label: 'Constelação',
 			items: [
-				{ label: 'Componentes', link: '/pt-br/guides/components/' },
-				{ label: 'Internacionalização (i18n)', link: '/pt-br/guides/i18n/' },
+				{ label: 'Andrômeda', link: '' },
+				{ label: 'Escorpião', link: '' },
 			],
 		},
 	]}
@@ -440,12 +436,12 @@ Groups of links can be collapsed by default by setting the `collapsed` property
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			// Collapse the group by default.
 			collapsed: true,
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
+				{ label: 'Andromeda', link: '/constellations/andromeda/' },
+				{ label: 'Orion', link: '/constellations/orion/' },
 			],
 		},
 	],
@@ -457,11 +453,11 @@ The configuration above generates the following sidebar:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			collapsed: true,
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
+				{ label: 'Andromeda', link: '' },
+				{ label: 'Orion', link: '' },
 			],
 		},
 	]}
@@ -473,10 +469,10 @@ The configuration above generates the following sidebar:
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			// Collapse the group and its autogenerated subgroups by default.
 			collapsed: true,
-			autogenerate: { directory: 'guides' },
+			autogenerate: { directory: 'constellations' },
 		},
 	],
 });
@@ -487,17 +483,15 @@ The configuration above generates the following sidebar:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			collapsed: true,
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
+				{ label: 'Carina', link: '' },
+				{ label: 'Centaurus', link: '' },
 				{
-					label: 'advanced',
+					label: 'seasonal',
 					collapsed: true,
-					items: [
-						{ label: 'Project Structure', link: '/guides/project-structure/' },
-					],
+					items: [{ label: 'Andromeda', link: '' }],
 				},
 			],
 		},
@@ -510,11 +504,11 @@ This behavior can be overridden by defining the `autogenerate.collapsed` propert
 starlight({
 	sidebar: [
 		{
-			label: 'Guides',
-			// Do not collapse the "Guides" group but collapse its
+			label: 'Constellations',
+			// Do not collapse the "Constellations" group but collapse its
 			// autogenerated subgroups.
 			collapsed: false,
-			autogenerate: { directory: 'guides', collapsed: true },
+			autogenerate: { directory: 'constellations', collapsed: true },
 		},
 	],
 });
@@ -525,16 +519,14 @@ The configuration above generates the following sidebar:
 <SidebarPreview
 	config={[
 		{
-			label: 'Guides',
+			label: 'Constellations',
 			items: [
-				{ label: 'Components', link: '/guides/components/' },
-				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
+				{ label: 'Carina', link: '' },
+				{ label: 'Centaurus', link: '' },
 				{
-					label: 'advanced',
+					label: 'seasonal',
 					collapsed: true,
-					items: [
-						{ label: 'Project Structure', link: '/guides/project-structure/' },
-					],
+					items: [{ label: 'Andromeda', link: '' }],
 				},
 			],
 		},