From 490fd98d4e7b38ec01c568eee0ab00844e59c53d Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Thu, 15 Jun 2023 21:00:33 +0200 Subject: Improve sidebar styles (#217) --- .changeset/clever-cameras-burn.md | 5 +++ docs/src/content/docs/reference/configuration.md | 43 +++++++++------------- packages/starlight/components/SidebarSublist.astro | 29 ++++++++++----- packages/starlight/style/props.css | 2 + packages/starlight/utils/user-config.ts | 10 +---- 5 files changed, 46 insertions(+), 43 deletions(-) create mode 100644 .changeset/clever-cameras-burn.md 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; - items: Array; - } - | { - label: string; - translations?: Record; - autogenerate: { - directory: string; - }; - }; -``` - -#### `LinkItem` +#### `SidebarItem` ```ts -interface LinkItem { +type SidebarItem = { label: string; - link: string; -} + translations?: Record; +} & ( + | { 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; } --- -
    +
      { Astro.props.sublist.map((entry) => ( -
    • +
    • {entry.type === 'link' ? ( - + {entry.label} ) : (
      -

      {entry.label}

      +

      {entry.label}

       - +
      )}
      • @@ -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; -const SidebarGroupSchema: z.ZodType< - | z.output - | z.output, - z.ZodTypeDef, - | z.input - | z.input -> = 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 ``. -- cgit