starlight-sidebar-topics-dropdown 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # starlight-sidebar-topics-dropdown
 
+## 0.4.0
+
+### Minor Changes
+
+- [#31](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/31) [`3193771`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/31937716171b020f414ece6783c17181fbd5fdcf) Thanks [@trueberryless](https://github.com/trueberryless)! - ⚠️ **BREAKING CHANGE:** The Starlight Sidebar Topics Dropdown plugin no longer provides the same ["Unnested Sidebar" configuration](https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unnested-sidebar/) like before. Please adapt your `astro.config.mjs` with the up-to-date guide on [how to configure a "Unnested Sidebar"](https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unnested-sidebar/#configure-an-unnested-sidebar).
+
+- [#31](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/31) [`db10526`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/db10526d49aab3ac8619159d40968dbc4748c9a0) Thanks [@trueberryless](https://github.com/trueberryless)! - ⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now version `0.32.0`.
+
+  Please use the `@astrojs/upgrade` command to upgrade your project:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+- [#31](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/31) [`db10526`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/db10526d49aab3ac8619159d40968dbc4748c9a0) Thanks [@trueberryless](https://github.com/trueberryless)! - ⚠️ **BREAKING CHANGE:** The Starlight Sidebar Topics Dropdown plugin no longer [overrides](https://starlight.astro.build/guides/overriding-components/) the [`<Pagination>` component](https://starlight.astro.build/reference/overrides/#pagination). If you were manually rendering `starlight-sidebar-topics-dropdown/overrides/Pagination.astro` in a custom override, you can now remove it.
+
+## 0.3.0
+
+### Minor Changes
+
+- [#16](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/16) [`9edb5dc`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/9edb5dca0215df684c4471ed7e1fe878617be91a) Thanks [@trueberryless](https://github.com/trueberryless)! - Adds support for Astro v5, drops support for Astro v4.
+
+  ⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now `0.30.0`.
+
+  Please follow the [upgrade guide](https://github.com/withastro/starlight/releases/tag/%40astrojs/starlight%400.30.0) to update your project.
+
+  Note that the [`legacy.collections` flag](https://docs.astro.build/en/reference/legacy-flags/#collections) is not supported by this plugin and you should update your collections to use Astro's new Content Layer API.
+
+### Patch Changes
+
+- [#18](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/18) [`2039e9a`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/2039e9a60659b5628c7406952bde0d453e38aeda) Thanks [@trueberryless](https://github.com/trueberryless)! - Add Unnested Sidebar configuration
+
 ## 0.2.2
 
 ### Patch Changes

package/components/Topics.astro

@@ -6,7 +6,7 @@ import { getRelativeLocaleUrl } from 'astro:i18n'
 import starlightConfig from 'virtual:starlight/user-config'
 import config from 'virtual:starlight-sidebar-topics-dropdown/config'
 
-import type { StarlightSidebarTopicsDropdownSharedConfig } from '../lib/config'
+import type { StarlightSidebarTopicsDropdownSharedConfig } from '../libs/config'
 
 interface Props {
   current: StarlightSidebarTopicsDropdownSharedConfig[number]
@@ -98,9 +98,9 @@ function getTranslation(translations: Record<string, string>, link: string, desc
   .starlight-sidebar-topics-dropdown-dropdown {
     position: relative;
     display: block;
-    width: calc(100% - 8px - 2 * 2px);
-    margin-left: calc(8px + 2px);
-    margin-right: calc(2px);
+    width: calc(100% - 2 * 2px);
+    margin-inline: 2px;
+		margin-top: 4px;
   }
 
   .starlight-sidebar-topics-dropdown-button {

package/components/starlight/Sidebar.astro

@@ -0,0 +1,28 @@
+---
+import { StarlightSidebarTopicsDropdownLocalsSymbol, type StarlightSidebarTopicsDropdownLocals } from '../../libs/locals'
+import Topics from '../Topics.astro'
+const { entry } = Astro.locals.starlightRoute
+// @ts-expect-error - See `libs/locals` for more information.
+const currentTopic = Astro.locals[StarlightSidebarTopicsDropdownLocalsSymbol] as StarlightSidebarTopicsDropdownLocals
+---
+
+{entry['data'].template !== 'splash' && currentTopic && <Topics current={currentTopic.config} />}
+
+<style is:global>
+	sl-sidebar-state-persist ul.top-level > li:not(:has(details)) {
+		margin-top: 0rem;
+	}
+	sl-sidebar-state-persist ul.top-level > li:has(details) {
+		margin-block: 0.5rem;
+	}
+	/* sl-sidebar-state-persist ul.top-level > li > a {
+		font-size: var(--sl-text-sm);
+	} */
+	sl-sidebar-state-persist ul.top-level > li > a[aria-current='page'] {
+		font-weight: 600;
+	}
+	sl-sidebar-state-persist ul.top-level > li > a[aria-current='false'] {
+		font-weight: 400;
+		color: var(--sl-color-gray-2);
+	}
+</style>

package/index.ts

@@ -1,82 +1,92 @@
-import type { StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types";
+import type {
+  StarlightPlugin,
+  StarlightUserConfig,
+} from "@astrojs/starlight/types";
 
 import {
-    StarlightSidebarTopicsDropdownConfigSchema,
-    type StarlightSidebarTopicsDropdownUserConfig,
-} from "./lib/config";
-import { overrideStarlightComponent, throwPluginError } from "./lib/plugin";
-import { vitePluginStarlightSidebarTopicsDropdown } from "./lib/vite";
+  StarlightSidebarTopicsDropdownConfigSchema,
+  type StarlightSidebarTopicsDropdownUserConfig,
+} from "./libs/config";
+import { overrideStarlightComponent, throwPluginError } from "./libs/plugin";
+import { vitePluginStarlightSidebarTopicsDropdown } from "./libs/vite";
 
 export type {
-    StarlightSidebarTopicsDropdownConfig,
-    StarlightSidebarTopicsDropdownUserConfig,
-} from "./lib/config";
+  StarlightSidebarTopicsDropdownConfig,
+  StarlightSidebarTopicsDropdownUserConfig,
+} from "./libs/config";
 
 export default function starlightSidebarTopicsDropdownPlugin(
-    userConfig: StarlightSidebarTopicsDropdownUserConfig
+  userConfig: StarlightSidebarTopicsDropdownUserConfig
 ): StarlightPlugin {
-    const parsedConfig = StarlightSidebarTopicsDropdownConfigSchema.safeParse(userConfig);
+  const parsedConfig =
+    StarlightSidebarTopicsDropdownConfigSchema.safeParse(userConfig);
 
-    if (!parsedConfig.success) {
-        throwPluginError(
-            `The provided plugin configuration is invalid.\n${parsedConfig.error.issues
-                .map((issue) => issue.message)
-                .join("\n")}`
-        );
-    }
+  if (!parsedConfig.success) {
+    throwPluginError(
+      `The provided plugin configuration is invalid.\n${parsedConfig.error.issues
+        .map((issue) => issue.message)
+        .join("\n")}`
+    );
+  }
 
-    const config = parsedConfig.data;
+  const config = parsedConfig.data;
 
-    return {
-        name: "starlight-sidebar-topics-dropdown-plugin",
-        hooks: {
-            setup({ addIntegration, command, config: starlightConfig, logger, updateConfig }) {
-                if (command !== "dev" && command !== "build") return;
+  return {
+    name: "starlight-sidebar-topics-dropdown-plugin",
+    hooks: {
+      "config:setup"({
+        addIntegration,
+        addRouteMiddleware,
+        command,
+        config: starlightConfig,
+        logger,
+        updateConfig,
+      }) {
+        if (command !== "dev" && command !== "build") return;
 
-                if (starlightConfig.sidebar) {
-                    throwPluginError(
-                        "It looks like you have a `sidebar` configured in your Starlight configuration. To use `starlight-sidebar-topics-dropdown`, create a new topic with your sidebar items.",
-                        "Learn more about topic configuration at https://starlight-sidebar-topics-dropdown.netlify.app/docs/configuration/"
-                    );
-                }
+        if (starlightConfig.sidebar) {
+          throwPluginError(
+            "It looks like you have a `sidebar` configured in your Starlight configuration. To use `starlight-sidebar-topics-dropdown`, create a new topic with your sidebar items.",
+            "Learn more about topic configuration at https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/configuration/"
+          );
+        }
 
-                const sidebar: StarlightUserConfig["sidebar"] = [];
+        addRouteMiddleware({
+          entrypoint: "starlight-sidebar-topics-dropdown/middleware",
+        });
 
-                for (const [index, topic] of config.entries()) {
-                    if ("items" in topic) {
-                        sidebar.push({ label: String(index), items: topic.items });
-                    }
-                }
-                updateConfig({
-                    components: {
-                        ...starlightConfig.components,
-                        ...overrideStarlightComponent(
-                            starlightConfig.components,
-                            logger,
-                            "Sidebar"
-                        ),
-                        ...overrideStarlightComponent(
-                            starlightConfig.components,
-                            logger,
-                            "Pagination"
-                        ),
-                    },
-                    sidebar,
-                });
+        const sidebar: StarlightUserConfig["sidebar"] = [];
 
-                addIntegration({
-                    name: "starlight-sidebar-topics-dropdown-integration",
-                    hooks: {
-                        "astro:config:setup": ({ updateConfig }) => {
-                            updateConfig({
-                                vite: {
-                                    plugins: [vitePluginStarlightSidebarTopicsDropdown(config)],
-                                },
-                            });
-                        },
-                    },
-                });
+        for (const [index, topic] of config.entries()) {
+          if ("items" in topic) {
+            sidebar.push({ label: String(index), items: topic.items });
+          }
+        }
+        updateConfig({
+          components: {
+            ...starlightConfig.components,
+            ...overrideStarlightComponent(
+              starlightConfig.components,
+              logger,
+              "Sidebar"
+            ),
+          },
+          sidebar,
+        });
+
+        addIntegration({
+          name: "starlight-sidebar-topics-dropdown-integration",
+          hooks: {
+            "astro:config:setup": ({ updateConfig }) => {
+              updateConfig({
+                vite: {
+                  plugins: [vitePluginStarlightSidebarTopicsDropdown(config)],
+                },
+              });
             },
-        },
-    };
+          },
+        });
+      },
+    },
+  };
 }

package/libs/config.ts

@@ -0,0 +1,82 @@
+import type { StarlightUserConfig } from "@astrojs/starlight/types";
+import { z } from "astro/zod";
+
+const sidebarTopicBadgeSchema = z.object({
+  text: z.union([z.string(), z.record(z.string())]),
+  variant: z
+    .enum(["note", "danger", "success", "caution", "tip", "default"])
+    .default("default"),
+});
+
+const sidebarTopicBaseSchema = z.object({
+  /**
+   * An optional badge to display next to the topic label.
+   *
+   * This option accepts the same configuration as the Starlight badge sidebar item configuration.
+   * @see https://starlight.astro.build/guides/sidebar/#badges
+   */
+  badge: z
+    .union([z.string(), sidebarTopicBadgeSchema])
+    .transform((badge) =>
+      typeof badge === "string"
+        ? { variant: "default" as const, text: badge }
+        : badge
+    )
+    .optional(),
+  /**
+   * The name of an optional icon to display before the topic label set to one of Starlight’s built-in icons.
+   * @see https://starlight.astro.build/reference/icons/#all-icons
+   */
+  icon: z.string().optional(),
+  /**
+   * The topic label visible at the top of the sidebar.
+   *
+   * The value can be a string, or for multilingual sites, an object with values for each different locale. When using
+   * the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).
+   */
+  label: z.union([z.string(), z.record(z.string())]),
+  /**
+   * The link to the topic’s content which an be a relative link to local files or the full URL of an external page.
+   *
+   * For internal links, the link can either be a page included in the items array or a different page acting as the
+   * topic’s landing page.
+   */
+  link: z.string(),
+});
+
+const sidebarTopicLinkSchema = sidebarTopicBaseSchema;
+
+const sidebarTopicGroupSchema = sidebarTopicBaseSchema.extend({
+  /**
+   * 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.
+   */
+  id: z.string().optional(),
+  /**
+   * The sidebar items (links and subcategories) to display for this topic.
+   *
+   * The topic’s sidebar navigation items. This represents the sidebar displayed when the topic `link` page or any of
+   * the pages configured in the `items` array is the current page.
+   */
+  items: z.any().array() as z.Schema<
+    NonNullable<StarlightUserConfig["sidebar"]>
+  >,
+});
+
+export const StarlightSidebarTopicsDropdownConfigSchema = z
+  .union([sidebarTopicGroupSchema, sidebarTopicLinkSchema])
+  .array();
+
+export type StarlightSidebarTopicsDropdownUserConfig = z.input<
+  typeof StarlightSidebarTopicsDropdownConfigSchema
+>;
+export type StarlightSidebarTopicsDropdownConfig = z.output<
+  typeof StarlightSidebarTopicsDropdownConfigSchema
+>;
+
+export type StarlightSidebarTopicsDropdownSharedConfig = (
+  | (z.output<typeof sidebarTopicLinkSchema> & { type: "link" })
+  | (Omit<z.output<typeof sidebarTopicGroupSchema>, "items"> & {
+      type: "group";
+    })
+)[];

package/libs/content.ts

@@ -0,0 +1,15 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
+import type { TopicFrontmatterSchema } from "../schema";
+export function isStarlightEntryWithTopic(
+  entry: StarlightEntry
+): entry is StarlightEntryWithTopic {
+  return (
+    "data" in entry &&
+    "topic" in (entry as StarlightEntryWithTopic).data &&
+    typeof (entry as StarlightEntryWithTopic).data.topic === "string"
+  );
+}
+export type StarlightEntry = StarlightRouteData["entry"];
+export type StarlightEntryWithTopic = StarlightEntry & {
+  data: TopicFrontmatterSchema;
+};

package/libs/i18n.ts

@@ -0,0 +1,27 @@
+import starlightConfig from "virtual:starlight/user-config";
+
+import { stripTrailingSlash } from "./pathname";
+
+export function getLocalizedSlug(
+  slug: string,
+  locale: string | undefined
+): string {
+  const slugLocale = getLocaleFromSlug(slug);
+  if (slugLocale === locale) return slug;
+  locale ??= "";
+  if (slugLocale === slug) return locale;
+
+  if (slugLocale) {
+    return stripTrailingSlash(
+      slug.replace(`${slugLocale}/`, locale ? `${locale}/` : "")
+    );
+  }
+
+  return slug ? `${locale}/${slug}` : locale;
+}
+
+export function getLocaleFromSlug(slug: string): string | undefined {
+  const locales = Object.keys(starlightConfig.locales ?? {});
+  const baseSegment = slug.split("/")[0];
+  return baseSegment && locales.includes(baseSegment) ? baseSegment : undefined;
+}

package/libs/locals.ts

@@ -0,0 +1,14 @@
+import type { StarlightSidebarTopicsDropdownSharedConfig } from "./config";
+
+/**
+ * We keep track of the current topic configuration using a variable stored using `Astro.locals` which will be reset for
+ * each new page. The value is tracked using an untyped symbol on purpose to avoid users to get autocomplete for it and
+ * avoid potential clashes with user-defined variables.
+ */
+export const StarlightSidebarTopicsDropdownLocalsSymbol = Symbol.for(
+  "starlight-sidebar-topics-dropdown:locals"
+);
+
+export interface StarlightSidebarTopicsDropdownLocals {
+  config: StarlightSidebarTopicsDropdownSharedConfig[number];
+}

package/libs/pathname.ts

@@ -0,0 +1,20 @@
+export function arePathnamesEqual(pathnameA: string, pathnameB: string) {
+  return (
+    stripLeadingAndTrailingSlashes(pathnameA) ===
+    stripLeadingAndTrailingSlashes(pathnameB)
+  );
+}
+
+export function stripLeadingAndTrailingSlashes(pathname: string): string {
+  return stripLeadingSlash(stripTrailingSlash(pathname));
+}
+
+export function stripLeadingSlash(pathname: string) {
+  if (pathname.startsWith("/")) pathname = pathname.slice(1);
+  return pathname;
+}
+
+export function stripTrailingSlash(pathname: string) {
+  if (pathname.endsWith("/")) pathname = pathname.slice(0, -1);
+  return pathname;
+}

package/libs/plugin.ts

@@ -0,0 +1,32 @@
+import type { StarlightUserConfig } from "@astrojs/starlight/types";
+import type { AstroIntegrationLogger } from "astro";
+import { AstroError } from "astro/errors";
+
+export function throwPluginError(message: string, hint?: string): never {
+  throw new AstroError(
+    message,
+    hint ??
+      `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`
+  );
+}
+
+export function overrideStarlightComponent(
+  components: StarlightUserConfig["components"],
+  logger: AstroIntegrationLogger,
+  component: keyof NonNullable<StarlightUserConfig["components"]>
+) {
+  if (components?.[component]) {
+    logger.warn(
+      `It looks like you already have a \`${component}\` component override in your Starlight configuration.`
+    );
+    logger.warn(
+      `To use \`starlight-sidebar-topics-dropdown\`, either remove your override or update it to render the content from \`starlight-sidebar-topics-dropdown/overrides/${component}.astro\`.`
+    );
+
+    return {};
+  }
+
+  return {
+    [component]: `starlight-sidebar-topics-dropdown/overrides/${component}.astro`,
+  };
+}

package/libs/sidebar.ts

@@ -0,0 +1,210 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
+
+import type { StarlightSidebarTopicsDropdownSharedConfig } from "./config";
+import { isStarlightEntryWithTopic, type StarlightEntry } from "./content";
+import { getLocaleFromSlug, getLocalizedSlug } from "./i18n";
+import { arePathnamesEqual, stripLeadingAndTrailingSlashes } from "./pathname";
+
+const absoluteLinkRegex = /^https?:\/\//;
+
+export function getCurrentTopic(
+  config: StarlightSidebarTopicsDropdownSharedConfig,
+  sidebar: SidebarEntry[],
+  currentSlug: string,
+  entry: StarlightEntry
+): Topic | undefined {
+  // If the current page has a topic ID, use it to find the topic.
+  const topicId = getTopicIdFromEntry(entry);
+  if (topicId) return getTopicById(config, sidebar, topicId);
+
+  // Start by checking if the current page is a topic root.
+  const topicFromSlug = getTopicFromSlug(config, sidebar, currentSlug);
+  if (topicFromSlug) return topicFromSlug;
+
+  // Otherwise, find the current topic by looking for the current page in the sidebar.
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar);
+  if (!currentSidebarTopic) return;
+
+  const currentTopicConfig =
+    config[Number.parseInt(currentSidebarTopic.label, 10)];
+  if (!currentTopicConfig) return;
+
+  const sidebarHasGroups =
+    currentSidebarTopic.entries.length !== 1 ||
+    currentSidebarTopic.entries[0]?.label !== "";
+
+  return {
+    config: currentTopicConfig,
+    sidebar: currentSidebarTopic.entries,
+    sidebarHasGroups,
+  };
+}
+
+export function isTopicFirstPage(
+  sidebar: SidebarEntry[],
+  currentSlug: string
+): boolean {
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar);
+  if (!currentSidebarTopic) return false;
+
+  const firstPage = getSidebarFirstPage(currentSidebarTopic.entries);
+  if (!firstPage) return false;
+
+  return arePathnamesEqual(
+    stripLeadingAndTrailingSlashes(firstPage.href),
+    currentSlug
+  );
+}
+
+export function isTopicLastPage(
+  sidebar: SidebarEntry[],
+  currentSlug: string
+): boolean {
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar);
+  if (!currentSidebarTopic) return false;
+
+  const lastPage = getSidebarLastPage(currentSidebarTopic.entries);
+  if (!lastPage) return false;
+
+  return arePathnamesEqual(
+    stripLeadingAndTrailingSlashes(lastPage.href),
+    currentSlug
+  );
+}
+
+function getSidebarFirstPage(sidebar: SidebarEntry[]) {
+  const entry = sidebar[0];
+  if (!entry) return;
+  if (entry.type === "link") return entry;
+
+  return getSidebarFirstPage(entry.entries);
+}
+
+function getSidebarLastPage(sidebar: SidebarEntry[]) {
+  const entry = sidebar.at(-1);
+  if (!entry) return;
+  if (entry.type === "link") return entry;
+
+  return getSidebarLastPage(entry.entries);
+}
+
+function getTopicFromSlug(
+  config: StarlightSidebarTopicsDropdownSharedConfig,
+  sidebar: SidebarEntry[],
+  slug: string
+): Topic | undefined {
+  let topicConfig: Topic["config"] | undefined;
+  let topicSidebar: Topic["sidebar"] | undefined;
+  let sidebarHasGroups = true;
+
+  // Start by checking if the current page is a topic homepage.
+  let groupTopicIndex = -1;
+  const slugLocale = getLocaleFromSlug(slug);
+
+  for (const topic of config) {
+    if (topic.type === "group") groupTopicIndex++;
+
+    if (
+      !absoluteLinkRegex.test(topic.link) &&
+      arePathnamesEqual(
+        getLocalizedSlug(
+          stripLeadingAndTrailingSlashes(topic.link),
+          slugLocale
+        ),
+        slug
+      ) &&
+      groupTopicIndex !== -1
+    ) {
+      const sidebarTopic = sidebar[groupTopicIndex];
+
+      if (sidebarTopic?.type === "group") {
+        topicConfig = topic;
+        topicSidebar = sidebarTopic.entries;
+        sidebarHasGroups =
+          sidebarTopic.entries.length !== 1 ||
+          sidebarTopic.entries[0]?.label !== "";
+      }
+
+      break;
+    }
+  }
+
+  if (!topicConfig || !topicSidebar) return;
+
+  return { config: topicConfig, sidebar: topicSidebar, sidebarHasGroups };
+}
+
+function getTopicById(
+  config: StarlightSidebarTopicsDropdownSharedConfig,
+  sidebar: SidebarEntry[],
+  id: string
+): Topic | undefined {
+  let topicConfig: Topic["config"] | undefined;
+  let topicSidebar: Topic["sidebar"] | undefined;
+  let sidebarHasGroups = true;
+  let groupTopicIndex = -1;
+  for (const topic of config) {
+    if (topic.type === "group") groupTopicIndex++;
+    if (topic.type === "group" && topic.id === id) {
+      const sidebarTopic = sidebar[groupTopicIndex];
+      if (sidebarTopic?.type === "group") {
+        topicConfig = topic;
+        topicSidebar = sidebarTopic.entries;
+        sidebarHasGroups =
+          sidebarTopic.entries.length !== 1 ||
+          sidebarTopic.entries[0]?.label !== "";
+      }
+      break;
+    }
+  }
+  if (!topicConfig || !topicSidebar) return;
+  return { config: topicConfig, sidebar: topicSidebar, sidebarHasGroups };
+}
+
+function getCurrentSidebarTopic(
+  sidebar: SidebarEntry[]
+): SidebarTopic | undefined {
+  let currentSidebarTopic: SidebarTopic | undefined;
+
+  for (const topic of sidebar) {
+    if (topic.type === "link") continue;
+
+    const currentSidebarEntry = getCurrentSidebarEntry(topic.entries);
+
+    if (currentSidebarEntry) {
+      currentSidebarTopic = topic;
+      break;
+    }
+  }
+
+  return currentSidebarTopic;
+}
+
+function getCurrentSidebarEntry(
+  sidebar: SidebarEntry[]
+): SidebarEntry | undefined {
+  return sidebar.find((entry) => {
+    if (entry.type === "link") {
+      return entry.isCurrent;
+    }
+
+    return getCurrentSidebarEntry(entry.entries);
+  });
+}
+
+function getTopicIdFromEntry(entry: StarlightEntry): string | undefined {
+  return isStarlightEntryWithTopic(entry) ? entry.data.topic : undefined;
+}
+
+type SidebarEntry = StarlightRouteData["sidebar"][number];
+
+interface SidebarTopic {
+  label: string;
+  entries: SidebarEntry[];
+}
+
+export interface Topic {
+  config: StarlightSidebarTopicsDropdownSharedConfig[number];
+  sidebar: SidebarEntry[];
+  sidebarHasGroups: boolean;
+}