Improve sidebar styles (#217)

5 files changed, 46 insertions, 43 deletions

diff --git a/.changeset/clever-cameras-burn.md b/.changeset/clever-cameras-burn.md
new file mode 100644
index 00000000..3bbffbc8
--- /dev/null
+++ b/.changeset/clever-cameras-burn.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Updated sidebar styles. Sidebars now support top-level links and groups are styled with a subtle border and indentation to improve comprehension of nesting.
diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
index b2cac362..48736d04 100644
--- a/docs/src/content/docs/reference/configuration.md
+++ b/docs/src/content/docs/reference/configuration.md
@@ -83,17 +83,24 @@ With this config, a `/introduction` page would have an edit link pointing to `ht
 
 ### `sidebar`
 
-**type:** [`SidebarGroup[]`](#sidebargroup)
+**type:** [`SidebarItem[]`](#sidebaritem)
 
 Configure your site’s sidebar navigation items.
 
-A sidebar is an array of groups, each with a `label` for the group and either an `items` array or an `autogenerate` configuration object.
+A sidebar is an array of links and groups of links.
+Each item must have a `label` and one of the following properties:
 
-You can manually set the contents of a group using `items`, which is an array that can include links and subgroups. You can also automatically generate the contents of a group from a specific directory of your docs, using `autogenerate`.
+- `link` — a single link to a specific URL, e.g. `'/home'` or `'https://example.com'`.
+
+- `items` — an array containing more sidebar links and subgroups.
+
+- `autogenerate` — an object specifying a directory of your docs to automatically generate a group of links from.
 
 ```js
 starlight({
   sidebar: [
+    // A single link item labelled “Home”.
+    { label: 'Home', link: '/' },
     // A group labelled “Start Here” containing two links.
     {
       label: 'Start Here',
@@ -142,31 +149,17 @@ sidebar: [
 ];
 ```
 
-#### `SidebarGroup`
-
-```ts
-type SidebarGroup =
-  | {
-      label: string;
-      translations?: Record<string, string>;
-      items: Array<LinkItem | SidebarGroup>;
-    }
-  | {
-      label: string;
-      translations?: Record<string, string>;
-      autogenerate: {
-        directory: string;
-      };
-    };
-```
-
-#### `LinkItem`
+#### `SidebarItem`
 
 ```ts
-interface LinkItem {
+type SidebarItem = {
   label: string;
-  link: string;
-}
+  translations?: Record<string, string>;
+} & (
+  | { link: string }
+  | { items: SidebarItem[] }
+  | { autogenerate: { directory: string } }
+);
 ```
 
 ### `locales`
diff --git a/packages/starlight/components/SidebarSublist.astro b/packages/starlight/components/SidebarSublist.astro
index b7a3b41a..27a13b82 100644
--- a/packages/starlight/components/SidebarSublist.astro
+++ b/packages/starlight/components/SidebarSublist.astro
@@ -4,24 +4,29 @@ import Icon from './Icon.astro';
 
 interface Props {
   sublist: SidebarEntry[];
+  nested?: boolean;
 }
 ---
 
-<ul>
+<ul class:list={{ 'top-level': !Astro.props.nested }}>
   {
     Astro.props.sublist.map((entry) => (
-      <li class:list={{ 'sidebar-group': entry.type === 'group' }}>
+      <li>
         {entry.type === 'link' ? (
-          <a href={entry.href} aria-current={entry.isCurrent && 'page'}>
+          <a
+            href={entry.href}
+            aria-current={entry.isCurrent && 'page'}
+            class:list={{ large: !Astro.props.nested }}
+          >
             {entry.label}
           </a>
         ) : (
           <details open>
             <summary>
-              <h2>{entry.label}</h2>
+              <h2 class="large">{entry.label}</h2>
               <Icon name="right-caret" class="caret" size="1.25rem" />
             </summary>
-            <Astro.self sublist={entry.entries} />
+            <Astro.self sublist={entry.entries} nested />
           </details>
         )}
       </li>
@@ -36,13 +41,19 @@ interface Props {
     padding: 0;
   }
 
-  h2 {
+  ul ul li {
+    margin-inline-start: var(--sl-sidebar-item-padding-inline);
+    border-inline-start: 1px solid var(--sl-color-hairline-light);
+    padding-inline-start: var(--sl-sidebar-item-padding-inline);
+  }
+
+  .large {
     font-size: var(--sl-text-lg);
     font-weight: 600;
     color: var(--sl-color-white);
   }
 
-  .sidebar-group + .sidebar-group {
+  .top-level > li + li {
     margin-top: 0.75rem;
   }
 
@@ -91,10 +102,10 @@ interface Props {
   }
 
   @media (min-width: 50rem) {
-    .sidebar-group + .sidebar-group {
+    .top-level > li + li {
       margin-top: 0.5rem;
     }
-    h2 {
+    .large {
       font-size: var(--sl-text-base);
     }
     a {
diff --git a/packages/starlight/style/props.css b/packages/starlight/style/props.css
index a8f95cb1..ccfd4539 100644
--- a/packages/starlight/style/props.css
+++ b/packages/starlight/style/props.css
@@ -43,6 +43,7 @@
   --sl-color-bg-nav: var(--sl-color-gray-6);
   --sl-color-bg-sidebar: var(--sl-color-gray-6);
   --sl-color-bg-inline-code: var(--sl-color-gray-5);
+  --sl-color-hairline-light: var(--sl-color-gray-5);
   --sl-color-hairline: var(--sl-color-gray-6);
   --sl-color-hairline-shade: var(--sl-color-black);
 
@@ -150,6 +151,7 @@
   --sl-color-bg-nav: var(--sl-color-gray-7);
   --sl-color-bg-sidebar: var(--sl-color-bg);
   --sl-color-bg-inline-code: var(--sl-color-gray-6);
+  --sl-color-hairline-light: var(--sl-color-gray-6);
   --sl-color-hairline-shade: var(--sl-color-gray-6);
 
   --sl-color-backdrop-overlay: hsla(225, 9%, 36%, 0.66);
diff --git a/packages/starlight/utils/user-config.ts b/packages/starlight/utils/user-config.ts
index cb2cf7ad..990407f2 100644
--- a/packages/starlight/utils/user-config.ts
+++ b/packages/starlight/utils/user-config.ts
@@ -95,14 +95,6 @@ const SidebarItemSchema = z.union([
 ]);
 export type SidebarItem = z.infer<typeof SidebarItemSchema>;
 
-const SidebarGroupSchema: z.ZodType<
-  | z.output<typeof ManualSidebarGroupSchema>
-  | z.output<typeof AutoSidebarGroupSchema>,
-  z.ZodTypeDef,
-  | z.input<typeof ManualSidebarGroupSchema>
-  | z.input<typeof AutoSidebarGroupSchema>
-> = z.union([ManualSidebarGroupSchema, AutoSidebarGroupSchema]);
-
 const UserConfigSchema = z.object({
   /** Title for your website. Will be used in metadata and as browser tab title. */
   title: z
@@ -202,7 +194,7 @@ const UserConfigSchema = z.object({
   defaultLocale: z.string().optional(),
 
   /** Configure your site’s sidebar navigation items. */
-  sidebar: SidebarGroupSchema.array().optional(),
+  sidebar: SidebarItemSchema.array().optional(),
 
   /**
    * Add extra tags to your site’s `<head>`.