···11+---
22+"starlight-sidebar-topics-dropdown-docs": minor
33+---
44+55+Update (and mostly remove) the documentation to match the new "just-a-component" package with the help of [HiDeoo](https://github.com/hideoo).
+63
.changeset/sad-bugs-pump.md
···11+---
22+"starlight-sidebar-topics-dropdown": minor
33+---
44+55+⚠️ **BREAKING CHANGE:** This plugin now uses the [Starlight Sidebar Topics](https://starlight-sidebar-topics.netlify.app/) plugin as a peer dependency. Please follow the upgrade guide below to migrate to the new version.
66+77+1. Install the [Starlight Sidebar Topics](https://starlight-sidebar-topics.netlify.app/) plugin:
88+99+ ```sh
1010+ npm i starlight-sidebar-topics
1111+ ```
1212+1313+2. Update the `starlight-sidebar-topics-dropdown` plugin in your `astro.config.mjs` (use the `starlight-sidebar-topics` plugin instead):
1414+1515+ ```diff lang="js"
1616+ // astro.config.mjs
1717+ -import starlightSidebarTopicsDropdown from "starlight-sidebar-topics-dropdown";
1818+ +import starlightSidebarTopics from "starlight-sidebar-topics";
1919+ ```
2020+2121+3. Exchange the `starlight-sidebar-topics-dropdown` plugin with the `starlight-sidebar-topics` plugin and add a manual override for the `Sidebar` component where you can use the dropdown component from the `starlight-sidebar-topics-dropdown` plugin:
2222+2323+ ```diff lang="js"
2424+ // astro.config.mjs
2525+ export default defineConfig({
2626+ integrations: [
2727+ starlight({
2828+ plugins: [
2929+ - starlightSidebarTopicsDropdown([
3030+ + starlightSidebarTopics([
3131+ // Your Starlight Sidebar Topics configuration here (unchanged).
3232+ ]),
3333+ ],
3434+ + components: {
3535+ + Sidebar: './src/components/Sidebar.astro',
3636+ + },
3737+ }),
3838+ ],
3939+ });
4040+ ```
4141+4242+4. Create an Astro component to replace the default Starlight `<Sidebar>` component with which will render the topic list dropdown menu and [re-use the default Starlight sidebar](https://starlight.astro.build/guides/overriding-components/#reuse-a-built-in-component):
4343+4444+ ```astro
4545+ ---
4646+ // src/components/Sidebar.astro
4747+ import Default from '@astrojs/starlight/components/Sidebar.astro';
4848+ import TopicsDropdown from 'starlight-sidebar-topics-dropdown/TopicsDropdown.astro';
4949+ ---
5050+5151+ {/* Render the topics dropdown menu. */}
5252+ <TopicsDropdown />
5353+ {/* Render the default sidebar. */}
5454+ <Default><slot /></Default>
5555+ ```
5656+5757+5. Update the schema import in `src/content.config.ts`:
5858+5959+ ```diff lang="ts"
6060+ // src/content.config.ts
6161+ -import { topicSchema } from "starlight-sidebar-topics-dropdown/schema";
6262+ +import { topicSchema } from "starlight-sidebar-topics/schema";
6363+ ```
···11+---
22+import Default from "@astrojs/starlight/components/Sidebar.astro";
33+import TopicsDropdown from "starlight-sidebar-topics-dropdown/TopicsDropdown.astro";
44+---
55+66+<TopicsDropdown />
77+<Default><slot /></Default>
+1-1
docs/src/content.config.ts
···11import { docsLoader } from "@astrojs/starlight/loaders";
22import { docsSchema } from "@astrojs/starlight/schema";
33import { defineCollection } from "astro:content";
44-import { topicSchema } from "starlight-sidebar-topics-dropdown/schema";
44+import { topicSchema } from "starlight-sidebar-topics/schema";
5566export const collections = {
77 docs: defineCollection({
-187
docs/src/content/docs/docs/configuration.mdx
···11----
22-title: Configuration
33-description: An overview of the configuration options supported by the Starlight Sidebar Topics Dropdown plugin.
44----
55-66-The Starlight Sidebar Topics Dropdown can be configured inside the `astro.config.mjs` configuration file of your project:
77-88-```js {12}
99-// astro.config.mjs
1010-// @ts-check
1111-import starlight from "@astrojs/starlight";
1212-import { defineConfig } from "astro/config";
1313-import starlightSidebarTopicsDropdown from "starlight-sidebar-topics-dropdown";
1414-1515-export default defineConfig({
1616- integrations: [
1717- starlight({
1818- plugins: [
1919- starlightSidebarTopicsDropdown([
2020- // Topics configuration goes here.
2121- ]),
2222- ],
2323- title: "My Docs",
2424- }),
2525- ],
2626-});
2727-```
2828-2929-## Topic configuration
3030-3131-The Starlight Sidebar Topics Dropdown plugin accepts an array of topics to display in the sidebar.
3232-3333-A topic can represent either a section of your documentation with its own sidebar configuration or a direct link to a specific URL, such as an external resource.
3434-3535-```js
3636-starlightSidebarTopicsDropdown([
3737- // A topic representing a guide section of your project.
3838- {
3939- label: "Guides",
4040- icon: "open-book",
4141- // The page to link to when the topic is clicked.
4242- link: "/guides/",
4343- // The sidebar configuration for the topic.
4444- items: [
4545- {
4646- label: "Start Here",
4747- items: ["guides/concepts", "guides/courses"],
4848- },
4949- { label: "Recipes", autogenerate: { directory: "guides/recipes" } },
5050- ],
5151- },
5252- // A topic redirecting to the Starlight documentation.
5353- {
5454- label: "Starlight docs",
5555- icon: "starlight",
5656- // The URL to the external resource to link to.
5757- link: "https://starlight.astro.build",
5858- },
5959-]);
6060-```
6161-6262-A topic can be configured using the following options:
6363-6464-### `label`
6565-6666-**required**
6767-**type:** `string | Record<string, string>`
6868-6969-The topic label visible at the top of the sidebar.
7070-7171-The value can be a string, or for multilingual sites, an object with values for each different locale.
7272-When using the object form, the keys must be BCP-47 tags (e.g. `en`, `fr`, or `zh-CN`):
7373-7474-```js {3-6}
7575-starlightSidebarTopicsDropdown([
7676- {
7777- label: {
7878- en: "Starlight documentation",
7979- fr: "Documentation de Starlight",
8080- },
8181- link: "https://starlight.astro.build",
8282- },
8383-]);
8484-```
8585-8686-### `link`
8787-8888-**required**
8989-**type:** `string`
9090-9191-The link to the topic's content which an be a relative link to local files or the full URL of an external page.
9292-9393-For internal links, the link can either be a page included in the [`items`](#items) array or a different page acting as the topic's landing page.
9494-9595-```js {4}
9696-starlightSidebarTopicsDropdown([
9797- {
9898- label: "Starlight docs",
9999- link: "https://starlight.astro.build",
100100- },
101101-]);
102102-```
103103-104104-### `items`
105105-106106-**type:** [`SidebarItem[]`](https://starlight.astro.build/reference/configuration/#sidebaritem)
107107-108108-The topic's sidebar navigation items.
109109-This represents the sidebar displayed when the topic [`link`](#link) page or any of the pages configured in the [`items`](#items) array is the current page.
110110-111111-This option accepts the same configuration as the [Starlight `sidebar` configuration](https://starlight.astro.build/reference/configuration/#sidebar).
112112-113113-```js {5-11}
114114-starlightSidebarTopicsDropdown([
115115- {
116116- label: "Guides",
117117- link: "/guides/",
118118- items: [
119119- {
120120- label: "Start Here",
121121- items: ["guides/concepts", "guides/courses"],
122122- },
123123- { label: "Recipes", autogenerate: { directory: "guides/recipes" } },
124124- ],
125125- },
126126-]);
127127-```
128128-129129-See the [“Sidebar Navigation”](https://starlight.astro.build/guides/sidebar/) guide in the Starlight docs to learn more about sidebar configuration.
130130-131131-:::note
132132-This plugin adds one special feature to the `items` configuration: the ability to autogenerate sidebar items at the root level of the topic. In other words, the sidebar will only show the topic switcher and a list of links which are not nested under any other item.
133133-134134-Read more about the [Unnested Sidebar](/docs/guides/unnested-sidebar/) feature.
135135-:::
136136-137137-### `id`
138138-139139-**type:** string
140140-An optional unique identifier for the topic that can be used to associate content pages that are not listed in any topic sidebar configuration with this topic.
141141-142142-```js {5}
143143-StarlightSidebarTopicsDropdown([
144144- {
145145- label: "Guides",
146146- link: "/guides/",
147147- id: "guides",
148148- items: [{ label: "Start Here", autogenerate: { directory: "guides" } }],
149149- },
150150-]);
151151-```
152152-153153-See the [“Unlisted Pages”](/docs/guides/unlisted-pages) guide to learn how to associate content pages with a specific topic.
154154-155155-### `icon`
156156-157157-**type:** string
158158-159159-The name of an optional icon to display before the topic label set to [one of Starlight's built-in icons](https://starlight.astro.build/reference/icons/#all-icons).
160160-161161-```js {5}
162162-starlightSidebarTopicsDropdown([
163163- {
164164- label: "Starlight docs",
165165- link: "https://starlight.astro.build",
166166- icon: "starlight",
167167- },
168168-]);
169169-```
170170-171171-### `badge`
172172-173173-**type:** <code>string | [BadgeConfig](https://starlight.astro.build/reference/configuration/#badgeconfig)</code>
174174-175175-An optional badge to display next to the topic label.
176176-177177-This option accepts the same configuration as the [Starlight `badge` sidebar item configuration](https://starlight.astro.build/guides/sidebar/#badges).
178178-179179-```js {5}
180180-starlightSidebarTopicsDropdown([
181181- {
182182- label: "Starlight docs",
183183- link: "https://starlight.astro.build",
184184- badge: { text: "Official", variant: "success" },
185185- },
186186-]);
187187-```
+48-73
docs/src/content/docs/docs/getting-started.mdx
···11---
22title: Getting Started
33-description: Learn how to split your documentation into different sections, called topics, each with its own sidebar.
33+description: Learn how to use a dropdown menu to switch between topics in your Starlight website.
44---
5566-An opinionated [Starlight](https://starlight.astro.build) plugin to split your documentation into different sections, called topics, each with its own sidebar.
77-88-Topics represent either a section of your documentation with its own sidebar configuration or a direct link to a specific URL, such as an external resource.
99-Topics are listed above the default Starlight sidebar links and can be used to navigate between different sections of your documentation.
66+This package exposes a dropdown menu component meant to be used as a [custom topic list](https://starlight-sidebar-topics.netlify.app/docs/guides/custom-topic-list/) for the [Starlight Sidebar Topics](https://starlight-sidebar-topics.netlify.app/) plugin.
107118:::tip[See it in action]
1212-At the top of the sidebar, you can find links to different topics used in this documentation, such as "Documentation" and "Demo" that each have their own sidebar configuration, while the "Starlight Docs" topic is a direct link to the Starlight documentation.
1313-:::
1414-1515-:::caution
1616-This plugin originates from [HiDeoo](https://github.com/HiDeoo) but is not affiliated with him. Nonetheless, huge thanks to him for his work on this plugin. We just changed the topic switcher component, the rest is the same. Make sure to check out [the original plugin](https://github.com/HiDeoo/starlight-sidebar-topics).
99+At the top of the sidebar, you can find the dropdown menu in action to switch between the different topics used in this documentation, such as "Documentation" and "Demo" that each have their own sidebar configuration, while the "Starlight Docs" topic is a direct link to the Starlight documentation.
1710:::
18111912## Prerequisites
20132114You will need to have a Starlight website set up.
2215If you don't have one yet, you can follow the ["Getting Started"](https://starlight.astro.build/getting-started) guide in the Starlight docs to create one.
1616+1717+You will also need to have the [Starlight Sidebar Topics](https://starlight-sidebar-topics.netlify.app/) plugin installed and configured.
1818+If you don't have it set up yet, you can follow the ["Getting Started"](https://starlight-sidebar-topics.netlify.app/getting-started) guide in the Starlight Sidebar Topics docs.
23192420## Installation
2521···28242925<Steps>
30263131-1. Starlight Sidebar Topics Dropdown is a Starlight [plugin](https://starlight.astro.build/reference/plugins/). Install it using your favorite package manager:
2727+1. Starlight Sidebar Topics Dropdown is a Starlight component. Install it using your favorite package manager:
32283333- <PackageManagers pkg="starlight-sidebar-topics-dropdown" />
2929+ <PackageManagers pkg="starlight-sidebar-topics-dropdown" />
34303535-2. Configure the plugin in your Starlight [configuration](https://starlight.astro.build/reference/configuration/#plugins) in the `astro.config.mjs` file by specifying an array of topics each with its own sidebar configuration.
3131+2. To replace the topic list built-in with the Starlight Sidebar Topics plugin by the dropdown menu provided by this package, configure a [component override](https://starlight.astro.build/guides/overriding-components/#how-to-override) in the `astro.config.mjs` file for the `<Sidebar>` component:
36323737- The following example shows how to configure two new topics named "Guides" and "Reference" linking to the `/guides/` and `/reference/` pages respectively with their own sidebar configuration:
3333+ ```diff lang="js"
3434+ // astro.config.mjs
3535+ // @ts-check
3636+ import starlight from '@astrojs/starlight'
3737+ import { defineConfig } from 'astro/config'
3838+ import starlightSidebarTopics from 'starlight-sidebar-topics'
38393939- ```diff lang="js"
4040- // astro.config.mjs
4141- // @ts-check
4242- import starlight from '@astrojs/starlight'
4343- import { defineConfig } from 'astro/config'
4444- +import starlightSidebarTopicsDropdown from 'starlight-sidebar-topics-dropdown'
4040+ export default defineConfig({
4141+ integrations: [
4242+ starlight({
4343+ plugins: [
4444+ starlightSidebarTopics([
4545+ // Your Starlight Sidebar Topics configuration here.
4646+ ]),
4747+ ],
4848+ + components: {
4949+ + // Override the default `Sidebar` component with a custom one.
5050+ + Sidebar: './src/components/Sidebar.astro',
5151+ + },
5252+ title: 'My Docs',
5353+ }),
5454+ ],
5555+ })
5656+ ```
45574646- export default defineConfig({
4747- integrations: [
4848- starlight({
4949- + plugins: [
5050- + starlightSidebarTopicsDropdown([
5151- + {
5252- + label: 'Guides',
5353- + link: '/guides/',
5454- + icon: 'open-book',
5555- + items: ['guides/getting-started', 'guides/manual-setup'],
5656- + },
5757- + {
5858- + label: 'Reference',
5959- + link: '/reference/',
6060- + icon: 'information',
6161- + items: ['reference/api', 'reference/components'],
6262- + },
6363- + ]),
6464- + ],
6565- - sidebar: [
6666- - {
6767- - label: 'Guides',
6868- - items: ['guides/getting-started', 'guides/manual-setup'],
6969- - },
7070- - {
7171- - label: 'Reference',
7272- - items: ['reference/api', 'reference/components'],
7373- - },
7474- - ],
7575- title: 'My Docs',
7676- }),
7777- ],
7878- })
7979- ```
8080-8181-3. [Start the development server](https://starlight.astro.build/getting-started/#start-the-development-server) to preview the changes.
8282-8383-</Steps>
5858+3. Create an Astro component to replace the default Starlight `<Sidebar>` component with which will render the topic list dropdown menu and [re-use the default Starlight sidebar](https://starlight.astro.build/guides/overriding-components/#reuse-a-built-in-component):
84598585-The Starlight Sidebar Topics Dropdown plugin behavior can be tweaked using various [topic configuration options](/docs/configuration/#topic-configuration).
6060+ ```astro
6161+ ---
6262+ // src/components/Sidebar.astro
6363+ import Default from '@astrojs/starlight/components/Sidebar.astro';
6464+ import TopicsDropdown from 'starlight-sidebar-topics-dropdown/TopicsDropdown.astro';
6565+ ---
86668787-## Component overrides
8888-8989-The Starlight Sidebar Topics Dropdown plugin uses a Starlight [component override](https://starlight.astro.build/guides/overriding-components/) for the [`Sidebar`](https://starlight.astro.build/reference/overrides/#sidebar) component to add the dropdown which enables choosing between different topics.
6767+ {/* Render the topics dropdown menu. */}
6868+ <TopicsDropdown />
6969+ {/* Render the default sidebar. */}
7070+ <Default><slot /></Default>
7171+ ```
90729191-If you have a custom `Sidebar` component override in your Starlight project, you will need to manually render the `Sidebar` component from the Starlight Sidebar Topics Dropdown plugin in your custom component:
7373+4. [Start the development server](https://starlight.astro.build/getting-started/#start-the-development-server) to preview the changes.
92749393-```diff lang="astro"
9494----
9595-// src/components/overrides/Sidebar.astro
9696-import Default from '@astrojs/starlight/components/Sidebar.astro'
9797-+import StarlightSidebarTopicsDropdownSidebar from 'starlight-sidebar-topics-dropdown/components/Sidebar.astro'
9898----
7575+</Steps>
9976100100-+<StarlightSidebarTopicsDropdownSidebar />
101101-<p>Custom content in the Sidebar override</p>
102102-<Default><slot /></Default>
103103-```
7777+You can also render the dropdown menu in a different location in your website by overriding different components.
7878+Lean more about [overriding components](https://starlight.astro.build/guides/overriding-components/) in the Starlight docs.
···11----
22-title: Unlisted Pages
33-description: Learn how to associate content pages that are not listed in any topic sidebar configuration with a specific topic.
44----
55-66-By default, the Starlight Sidebar Topics Dropdown plugin expect that every [content pages](https://starlight.astro.build/guides/pages/#content-pages) in your project is associated with a topic.
77-This is done by including the content page in a [topic sidebar configuration](/docs/configuration#items) and the plugin will automatically determine which sidebar to display based on the current page.
88-99-However, there are cases where you may want to have a content page that is not listed in any topic sidebar while still displaying the sidebar of a specific topic.
1010-1111-:::note
1212-As an example for such a page, you can visit [the secret demo page](/demo/secret), which is not displayed in the sidebar, but is associated with the “Demo” topic through the `topic: demo` frontmatter entry.
1313-:::
1414-1515-## Configure content collections
1616-1717-Starlight is built on top of Astro's [content collections](https://docs.astro.build/en/guides/content-collections/), which are configured in the `src/content.config.ts` file.
1818-1919-To add support for unlisted content pages, update the content config file to add support for associating content pages with a specific topic:
2020-2121-```diff lang=ts ins="{ extend: topicSchema }"
2222-// src/content.config.ts
2323-import { defineCollection } from 'astro:content'
2424-import { docsLoader } from '@astrojs/starlight/loaders'
2525-import { docsSchema } from '@astrojs/starlight/schema'
2626-+import { topicSchema } from 'starlight-sidebar-topics-dropdown/schema'
2727-2828-export const collections = {
2929- docs: defineCollection({
3030- loader: docsLoader(),
3131- schema: docsSchema({ extend: topicSchema })
3232- }),
3333-}
3434-```
3535-3636-## Create a topic ID
3737-3838-To associate an unlisted content page with a specific topic, the topic must define an [`id`](/docs/configuration#id) in its [configuration](/docs/configuration#topic-configuration):
3939-4040-```js {16-17}
4141-// astro.config.mjs
4242-// @ts-check
4343-import starlight from "@astrojs/starlight";
4444-import { defineConfig } from "astro/config";
4545-import StarlightSidebarTopicsDropdown from "starlight-sidebar-topics-dropdown";
4646-4747-export default defineConfig({
4848- integrations: [
4949- starlight({
5050- plugins: [
5151- StarlightSidebarTopicsDropdown([
5252- {
5353- label: "Guides",
5454- icon: "open-book",
5555- link: "/guides/",
5656- // ID used to associate content pages with this topic.
5757- id: "guides",
5858- items: ["guides/concepts", "guides/courses"],
5959- },
6060- ]),
6161- ],
6262- title: "My Docs",
6363- }),
6464- ],
6565-});
6666-```
6767-6868-## Associate a page with a topic
6969-7070-To associate an unlisted content page with a specific topic, you can use the `topic` [frontmatter](https://starlight.astro.build/reference/frontmatter/) field in the page's content file:
7171-7272-```md {4}
7373----
7474-# src/content/docs/guides/support.md
7575-title: Support
7676-topic: guides
7777----
7878-7979-This is the support page.
8080-```
8181-8282-For example, given the following file structure based on this guide:
8383-8484-import { FileTree } from "@astrojs/starlight/components";
8585-8686-<FileTree>
8787-8888-- src/
8989- - content/
9090- - docs/
9191- - guides/
9292- - concepts.md
9393- - courses.md
9494- - support.md
9595-9696-</FileTree>
9797-9898-Visiting the `guides/concepts`, `guides/courses`, and `guides/support` pages will all display the sidebar of the "Guides" topic.
9999-100100-- `guides/concepts` and `guides/courses` are explicitly listed in the "Guides" topic sidebar configuration under the [`items`](/docs/configuration#items) key.
101101-- `guides/support` is not listed in the "Guides" topic sidebar configuration but is associated with the "Guides" topic through the `topic: guides` frontmatter entry.
···11----
22-title: Unnested Sidebar
33-description: Learn how to configure the Starlight Sidebar Topics Dropdown plugin to display a single-level sidebar without nesting items.
44----
55-66-By default, the Starlight Sidebar Topics Dropdown plugin displays a nested sidebar with multiple levels of items. This allows you to organize your documentation essentially on four levels:
77-88-1. **Topics**: Representing the main sections of your documentation.
99-2. **Sidebar Groups**: Representing the sub-sections of a topic.
1010-3. **Sidebar Items / Pages**: Representing the individual pages of a sidebar group.
1111-4. **Table of Contents**: Representing the headings of a page.
1212-1313-However, sometimes you don't need so many levels of nesting and want to display a single-level sidebar with all items directly under the topic. This plugin makes this possible by providing the option to configure an unnested sidebar, which will result in only three levels of organization:
1414-1515-1. **Topics**: Representing the main sections of your documentation.
1616-2. **Sidebar Items / Pages**: Representing the individual pages of a topic.
1717-3. **Table of Contents**: Representing the headings of a page.
1818-1919-In other words, there are no groups in the sidebar, only the items of a topic are displayed directly under the topic.
2020-2121-## Configure an unnested sidebar
2222-2323-To configure an unnested sidebar, list the items directly inside the [`items` topic array](/docs/configuration#items) using the `slug` option provided by the [`SidebarItem` type](https://starlight.astro.build/reference/configuration/#sidebaritem). Starlight Sidebar Topics Dropdown Plugin automatically applies CSS to make the items look right.
2424-2525-Unfortunately, there is no option for autogenerating an unnested sidebar, which is currently a limitation by Starlight.
2626-2727-Here is an example of this feature:
2828-2929-```js "label: \"\""
3030-export default defineConfig({
3131- integrations: [
3232- starlight({
3333- title: "Starlight Sidebar Topics Dropdown",
3434- plugins: [
3535- starlightSidebarTopicsDropdown([
3636- {
3737- id: "unnested-sidebar",
3838- label: "Unnested Sidebar",
3939- link: "/unnested-sidebar/",
4040- icon: "right-caret",
4141- items: [
4242- { slug: "unnested-sidebar" },
4343- { slug: "unnested-sidebar/lorem-ipsum" },
4444- ],
4545- },
4646- ]),
4747- ],
4848- }),
4949- ],
5050-});
5151-```
5252-5353-You can see how the sidebar is displayed in the [Unnested Sidebar](/unnested-sidebar/lorem-ipsum/) topic.
···11----
22-title: Lorem ispum
33----
44-55-:::note
66-This page exists solely for demonstration purposes and contains no useful information.
77-See the Starlight Multiple Sidebar Dropdown plugin [Unnested Sidebar Guide](/docs/guides/unnested-sidebar/) for more information.
88-:::
99-1010-Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
-10
docs/src/content/docs/unnested-sidebar/index.md
···11----
22-title: Index
33----
44-55-:::note
66-This page exists solely for demonstration purposes and contains no useful information.
77-See the Starlight Multiple Sidebar Dropdown plugin [Unnested Sidebar Guide](/docs/guides/unnested-sidebar/) for more information.
88-:::
99-1010-Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
···11----
22-title: Lorem ispum 2
33----
44-55-:::note
66-This page exists solely for demonstration purposes and contains no useful information.
77-See the Starlight Multiple Sidebar Dropdown plugin [Unnested Sidebar Guide](/docs/guides/unnested-sidebar/) for more information.
88-:::
99-1010-Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
···11----
22-title: Lorem ispum
33----
44-55-:::note
66-This page exists solely for demonstration purposes and contains no useful information.
77-See the Starlight Multiple Sidebar Dropdown plugin [Unnested Sidebar Guide](/docs/guides/unnested-sidebar/) for more information.
88-:::
99-1010-Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
···11-import type { StarlightUserConfig } from "@astrojs/starlight/types";
22-import { z } from "astro/zod";
33-44-const sidebarTopicBadgeSchema = z.object({
55- text: z.union([z.string(), z.record(z.string())]),
66- variant: z
77- .enum(["note", "danger", "success", "caution", "tip", "default"])
88- .default("default"),
99-});
1010-1111-const sidebarTopicBaseSchema = z.object({
1212- /**
1313- * An optional badge to display next to the topic label.
1414- *
1515- * This option accepts the same configuration as the Starlight badge sidebar item configuration.
1616- * @see https://starlight.astro.build/guides/sidebar/#badges
1717- */
1818- badge: z
1919- .union([z.string(), sidebarTopicBadgeSchema])
2020- .transform((badge) =>
2121- typeof badge === "string"
2222- ? { variant: "default" as const, text: badge }
2323- : badge
2424- )
2525- .optional(),
2626- /**
2727- * The name of an optional icon to display before the topic label set to one of Starlight’s built-in icons.
2828- * @see https://starlight.astro.build/reference/icons/#all-icons
2929- */
3030- icon: z.string().optional(),
3131- /**
3232- * The topic label visible at the top of the sidebar.
3333- *
3434- * The value can be a string, or for multilingual sites, an object with values for each different locale. When using
3535- * the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).
3636- */
3737- label: z.union([z.string(), z.record(z.string())]),
3838- /**
3939- * The link to the topic’s content which an be a relative link to local files or the full URL of an external page.
4040- *
4141- * For internal links, the link can either be a page included in the items array or a different page acting as the
4242- * topic’s landing page.
4343- */
4444- link: z.string(),
4545-});
4646-4747-const sidebarTopicLinkSchema = sidebarTopicBaseSchema;
4848-4949-const sidebarTopicGroupSchema = sidebarTopicBaseSchema.extend({
5050- /**
5151- * An optional unique identifier for the topic that can be used to associate content pages that are not listed in any
5252- * topic sidebar configuration with this topic.
5353- */
5454- id: z.string().optional(),
5555- /**
5656- * The sidebar items (links and subcategories) to display for this topic.
5757- *
5858- * The topic’s sidebar navigation items. This represents the sidebar displayed when the topic `link` page or any of
5959- * the pages configured in the `items` array is the current page.
6060- */
6161- items: z.any().array() as z.Schema<
6262- NonNullable<StarlightUserConfig["sidebar"]>
6363- >,
6464-});
6565-6666-export const StarlightSidebarTopicsDropdownConfigSchema = z
6767- .union([sidebarTopicGroupSchema, sidebarTopicLinkSchema])
6868- .array();
6969-7070-export type StarlightSidebarTopicsDropdownUserConfig = z.input<
7171- typeof StarlightSidebarTopicsDropdownConfigSchema
7272->;
7373-export type StarlightSidebarTopicsDropdownConfig = z.output<
7474- typeof StarlightSidebarTopicsDropdownConfigSchema
7575->;
7676-7777-export type StarlightSidebarTopicsDropdownSharedConfig = (
7878- | (z.output<typeof sidebarTopicLinkSchema> & { type: "link" })
7979- | (Omit<z.output<typeof sidebarTopicGroupSchema>, "items"> & {
8080- type: "group";
8181- })
8282-)[];
···11-import type { StarlightSidebarTopicsDropdownSharedConfig } from "./config";
22-33-/**
44- * We keep track of the current topic configuration using a variable stored using `Astro.locals` which will be reset for
55- * each new page. The value is tracked using an untyped symbol on purpose to avoid users to get autocomplete for it and
66- * avoid potential clashes with user-defined variables.
77- */
88-export const StarlightSidebarTopicsDropdownLocalsSymbol = Symbol.for(
99- "starlight-sidebar-topics-dropdown:locals"
1010-);
1111-1212-export interface StarlightSidebarTopicsDropdownLocals {
1313- config: StarlightSidebarTopicsDropdownSharedConfig[number];
1414-}
···11-import { AstroError } from "astro/errors";
22-33-export function throwPluginError(message: string, hint?: string): never {
44- throw new AstroError(
55- message,
66- hint ??
77- `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/issues/new/choose`
88- );
99-}
···11-import type { StarlightUserConfig } from "@astrojs/starlight/types";
22-import type { AstroIntegrationLogger } from "astro";
33-44-export function overrideStarlightComponent(
55- components: StarlightUserConfig["components"],
66- logger: AstroIntegrationLogger,
77- override: keyof NonNullable<StarlightUserConfig["components"]>,
88- component: string
99-) {
1010- if (components?.[override]) {
1111- logger.warn(
1212- `It looks like you already have a \`${override}\` component override in your Starlight configuration.`
1313- );
1414- logger.warn(
1515- `To use \`starlight-sidebar-topics-dropdown\`, either remove your override or update it to render the content from \`starlight-sidebar-topics-dropdown/components/${component}.astro\`.`
1616- );
1717-1818- return {};
1919- }
2020-2121- return {
2222- [override]: `starlight-sidebar-topics-dropdown/overrides/${override}.astro`,
2323- };
2424-}
···11-import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
22-import config from "virtual:starlight-sidebar-topics-dropdown/config";
33-44-import {
55- type StarlightSidebarTopicsDropdownLocals,
66- StarlightSidebarTopicsDropdownLocalsSymbol,
77-} from "./libs/locals";
88-import { throwPluginError } from "./libs/plugin";
99-import {
1010- getCurrentTopic,
1111- isTopicFirstPage,
1212- isTopicLastPage,
1313-} from "./libs/sidebar";
1414-1515-export const onRequest = defineRouteMiddleware((context) => {
1616- const { starlightRoute } = context.locals;
1717- const { entry, id, pagination, sidebar } = starlightRoute;
1818-1919- if (entry["data"].template !== "splash") {
2020- const currentTopic = getCurrentTopic(config, sidebar, id, entry);
2121-2222- if (!currentTopic)
2323- throwPluginError(
2424- `Failed to find the topic for the \`${id}\` page.`,
2525- `Either include this page in the sidebar configuration of the desired topic using the \`items\` property or to associate an unlisted page with a topic, use the \`topic\` frontmatter property and set it to the desired topic ID.
2626- Learn more about unlisted pages in the ["Unlisted pages"](https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unlisted-pages/) guide.`
2727- );
2828-2929- starlightRoute.sidebar = currentTopic.sidebar;
3030- // @ts-expect-error - See `libs/locals` for more information.
3131- context.locals[StarlightSidebarTopicsDropdownLocalsSymbol] = {
3232- config: currentTopic.config,
3333- } satisfies StarlightSidebarTopicsDropdownLocals;
3434-3535- if (isTopicFirstPage(sidebar, id)) {
3636- pagination.prev = undefined;
3737- }
3838-3939- if (isTopicLastPage(sidebar, id)) {
4040- pagination.next = undefined;
4141- }
4242- }
4343-});
···11-import { z } from "astro/zod";
22-33-export const topicSchema = z.object({
44- /**
55- * ID of the topic to associate with the current page if the page is not listed in any topic sidebar configuration.
66- *
77- * @see https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unlisted-pages/
88- */
99- topic: z.string().optional(),
1010-});
1111-export type TopicFrontmatterSchema = z.input<typeof topicSchema>;