starlight-sidebar-topics-dropdown 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# `starlight-sidebar-topics-dropdown`
+
+Starlight plugin to split your docs page into multiple subpages and switch between them with a dropdown menu in the sidebar.
+
+## Documentation
+
+Want to get started immediately?
+
+Check out the `starlight-sidebar-topics-dropdown` getting started guide.
+
+## License
+
+Licensed under the MIT License, Copyright © trueberryless-org.
+
+See [LICENSE](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/blob/main/LICENSE) for more information.

package/components/Topics.astro

@@ -0,0 +1,253 @@
+---
+import { Badge, Icon } from '@astrojs/starlight/components'
+import { AstroError } from 'astro/errors'
+import type { ComponentProps } from 'astro/types'
+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'
+
+interface Props {
+  current: StarlightSidebarTopicsDropdownSharedConfig[number]
+}
+
+const { current } = Astro.props
+
+const defaultLang = starlightConfig.defaultLocale?.lang || starlightConfig.defaultLocale?.locale || 'en'
+
+function getTranslation(translations: Record<string, string>, link: string, description: string) {
+  const defaultTranslation = translations[defaultLang]
+
+  if (!defaultTranslation) {
+    throw new AstroError(
+      `The ${description} for "${link}" must have a key for the default language "${defaultLang}".`,
+      'Update the Starlight config to include a topic label for the default language.',
+    )
+  }
+
+  let translation = defaultTranslation
+
+  if (Astro.currentLocale) {
+    translation = translations[Astro.currentLocale] ?? defaultTranslation
+  }
+
+  return translation
+}
+---
+
+<div class="starlight-sidebar-topics-dropdown-dropdown">
+  <button id="starlight-sidebar-topics-dropdown-button" class="starlight-sidebar-topics-dropdown-button">
+    {current.icon && (
+      <div class="starlight-sidebar-topics-dropdown-button-icon">
+        <Icon name={current.icon as ComponentProps<typeof Icon>['name']} />
+      </div>
+    )}
+    <span class="starlight-sidebar-topics-dropdown-button-label">{typeof current.label === 'string' ? current.label : getTranslation(current.label, current.link, 'topic label')}</span>
+    {current.badge && (
+      <Badge
+        class="starlight-sidebar-topics-dropdown-badge"
+        text={
+          typeof current.badge.text === 'string'
+            ? current.badge.text
+            : getTranslation(current.badge.text, current.link, 'current badge text')
+        }
+        variant={current.badge.variant}
+      />
+    )}
+    <svg width="16" height="16" viewBox="0 0 15 15" fill="none" xmlns="http://www.w3.org/2000/svg" class="h-4 w-4 opacity-50" aria-hidden="true"><path d="M4.93179 5.43179C4.75605 5.60753 4.75605 5.89245 4.93179 6.06819C5.10753 6.24392 5.39245 6.24392 5.56819 6.06819L7.49999 4.13638L9.43179 6.06819C9.60753 6.24392 9.89245 6.24392 10.0682 6.06819C10.2439 5.89245 10.2439 5.60753 10.0682 5.43179L7.81819 3.18179C7.73379 3.0974 7.61933 3.04999 7.49999 3.04999C7.38064 3.04999 7.26618 3.0974 7.18179 3.18179L4.93179 5.43179ZM10.0682 9.56819C10.2439 9.39245 10.2439 9.10753 10.0682 8.93179C9.89245 8.75606 9.60753 8.75606 9.43179 8.93179L7.49999 10.8636L5.56819 8.93179C5.39245 8.75606 5.10753 8.75606 4.93179 8.93179C4.75605 9.10753 4.75605 9.39245 4.93179 9.56819L7.18179 11.8182C7.35753 11.9939 7.64245 11.9939 7.81819 11.8182L10.0682 9.56819Z" fill="currentColor" fill-rule="evenodd" clip-rule="evenodd"></path></svg>
+  </button>
+
+  <div id="starlight-sidebar-topics-dropdown-menu" class="starlight-sidebar-topics-dropdown-menu" hidden>
+    {
+      config.map((topic) => {
+        const isLinkTopic = topic.type === 'link'
+        const isCurrent = isLinkTopic ? false : topic.label === current.label && topic.link === current.link
+        const link =
+          !isLinkTopic && Astro.currentLocale ? getRelativeLocaleUrl(Astro.currentLocale, topic.link) : topic.link
+        const label =
+          typeof topic.label === 'string' ? topic.label : getTranslation(topic.label, topic.link, 'topic label')
+
+        return (
+          <a href={link} class:list={{ 'starlight-sidebar-topics-dropdown-item': true, 'starlight-sidebar-topics-dropdown-current-item': isCurrent }}>
+            {topic.icon && (
+              <div class="starlight-sidebar-topics-dropdown-icon">
+                <Icon name={topic.icon as ComponentProps<typeof Icon>['name']} />
+              </div>
+            )}
+            <span class="starlight-sidebar-topics-dropdown-label">{label}</span>
+            {topic.badge && (
+              <Badge
+                class="starlight-sidebar-topics-dropdown-badge"
+                text={
+                  typeof topic.badge.text === 'string'
+                    ? topic.badge.text
+                    : getTranslation(topic.badge.text, topic.link, 'topic badge text')
+                }
+                variant={topic.badge.variant}
+              />
+            )}
+          </a>
+        )
+      })
+    }
+  </div>
+</div>
+
+<style>
+  .starlight-sidebar-topics-dropdown-dropdown {
+    position: relative;
+    display: block;
+    width: calc(100% - 8px - 2 * 2px);
+    margin-left: calc(8px + 2px);
+    margin-right: calc(2px);
+  }
+
+  .starlight-sidebar-topics-dropdown-button {
+    display: flex;
+    align-items: center;
+    background-color: var(--sl-color-gray-6);
+    border: none;
+    border-radius: 0.25rem;
+    color: var(--sl-color-white);
+    padding: 0.3rem 0.5rem;
+    cursor: pointer;
+    width: 100%;
+  }
+
+  .starlight-sidebar-topics-dropdown-button::before {
+    content: '';
+    background-color: var(--sl-color-gray-5);
+    border-radius: 0.25rem;
+    inset: -2px;
+    position: absolute;
+    z-index: -1;
+  }
+
+
+  .starlight-sidebar-topics-dropdown-button:has(.starlight-sidebar-topics-dropdown-button-icon)::before {
+    content: '';
+    background-image: linear-gradient(to right, var(--sl-color-text-accent) calc(1.4rem + 16px + 2px), var(--sl-color-gray-5) 0);
+  }
+
+  .starlight-sidebar-topics-dropdown-button:has(.starlight-sidebar-topics-dropdown-button-icon) {
+    background: linear-gradient(to right, var(--sl-color-text-accent) calc(1.4rem + 16px), var(--sl-color-gray-6) 0);
+  }
+  
+  .starlight-sidebar-topics-dropdown-button-icon {
+    align-items: center;
+    border-radius: 0.25rem;
+    display: flex;
+    justify-content: center;
+    padding: 0.2rem;
+    background-color: var(--sl-color-text-accent);
+    color: var(--sl-color-text-invert);
+  }
+
+  .starlight-sidebar-topics-dropdown-button-label {
+    font-weight: 600;
+    margin-right: 0.5rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .starlight-sidebar-topics-dropdown-button:has(.starlight-sidebar-topics-dropdown-button-icon) .starlight-sidebar-topics-dropdown-button-label {
+    font-weight: 600;
+    margin-left: 1rem;
+  }
+
+  .starlight-sidebar-topics-dropdown-label {
+    font-weight: 600;
+    margin-right: 0.5rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .starlight-sidebar-topics-dropdown-item:has(.starlight-sidebar-topics-dropdown-icon) .starlight-sidebar-topics-dropdown-label {
+    margin-left: 0.5rem;
+  }
+
+  .starlight-sidebar-topics-dropdown-button>svg {
+    margin-left: auto;
+    font-size: 1rem;
+    color: var(--sl-color-white);
+  }
+
+  .starlight-sidebar-topics-dropdown-menu {
+    display: block;
+    position: absolute;
+    margin-top: 0.25rem;
+    width: 100%;
+    background-color: var(--sl-color-gray-6);
+    box-shadow: 0 8px 16px rgba(0, 0, 0, 0.2);
+    min-width: 200px;
+    padding: 0.5rem;
+    border-radius: 0.25rem;
+    z-index: 1000000;
+  }
+
+  .starlight-sidebar-topics-dropdown-menu[hidden] {
+    display: none;
+  }
+
+  .starlight-sidebar-topics-dropdown-item {
+    display: flex;
+    align-items: center;
+    padding: 0.3em;
+    color: var(--sl-color-white);
+    text-decoration: none;
+    font-weight: 600;
+  }
+
+  .starlight-sidebar-topics-dropdown-icon {
+    align-items: center;
+    border-radius: 0.25rem;
+    border: 1px solid var(--sl-color-gray-4);
+    display: flex;
+    justify-content: center;
+    padding: 0.25rem;
+  }
+
+  .starlight-sidebar-topics-dropdown-button:is(.starlight-sidebar-topics-dropdown-current, :hover, :focus-visible) .starlight-sidebar-topics-dropdown-icon {
+    background-color: var(--sl-color-text-accent);
+    border-color: var(--sl-color-text-accent);
+    color: var(--sl-color-text-invert);
+  }  
+
+  .starlight-sidebar-topics-dropdown-item:is(:hover, .starlight-sidebar-topics-dropdown-current-item) .starlight-sidebar-topics-dropdown-icon {
+    background-color: var(--sl-color-text-accent);
+    border-color: var(--sl-color-text-accent);
+    color: var(--sl-color-text-invert);
+  }
+
+  .starlight-sidebar-topics-dropdown-badge {
+    margin-left: 0.25rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+</style>
+
+<script>
+  const dropdownButton = document.getElementById('starlight-sidebar-topics-dropdown-button');
+  const dropdownMenu = document.getElementById('starlight-sidebar-topics-dropdown-menu');
+
+  if (!dropdownButton || !dropdownMenu) {
+    throw new Error('Dropdown elements not found');
+  }
+
+  dropdownButton.addEventListener('click', () => {
+    const isOpen = !dropdownMenu.hidden;
+    dropdownMenu.hidden = isOpen;
+  });
+
+  function closeDropdown(event) {
+    if (dropdownMenu && !dropdownMenu.contains(event.target) && dropdownButton && !dropdownButton.contains(event.target)) {
+      dropdownMenu.hidden = true;
+    }
+  }
+
+  document.addEventListener('click', closeDropdown);
+</script>

package/index.ts

@@ -0,0 +1,82 @@
+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";
+
+export type {
+    StarlightSidebarTopicsDropdownConfig,
+    StarlightSidebarTopicsDropdownUserConfig,
+} from "./lib/config";
+
+export default function starlightSidebarTopicsDropdownPlugin(
+    userConfig: StarlightSidebarTopicsDropdownUserConfig
+): StarlightPlugin {
+    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")}`
+        );
+    }
+
+    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;
+
+                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/"
+                    );
+                }
+
+                const sidebar: StarlightUserConfig["sidebar"] = [];
+
+                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,
+                });
+
+                addIntegration({
+                    name: "starlight-sidebar-topics-dropdown-integration",
+                    hooks: {
+                        "astro:config:setup": ({ updateConfig }) => {
+                            updateConfig({
+                                vite: {
+                                    plugins: [vitePluginStarlightSidebarTopicsDropdown(config)],
+                                },
+                            });
+                        },
+                    },
+                });
+            },
+        },
+    };
+}

package/lib/config.ts

@@ -0,0 +1,69 @@
+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({
+    /**
+     * 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/lib/i18n.ts

@@ -0,0 +1,22 @@
+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/lib/pathname.ts

@@ -0,0 +1,17 @@
+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/lib/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/HiDeoo/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/lib/sidebar.ts

@@ -0,0 +1,140 @@
+import type { Props } from "@astrojs/starlight/props";
+
+import type { StarlightSidebarTopicsDropdownSharedConfig } from "./config";
+import { getLocaleFromSlug, getLocalizedSlug } from "./i18n";
+import { arePathnamesEqual, stripLeadingAndTrailingSlashes } from "./pathname";
+
+const absoluteLinkRegex = /^https?:\/\//;
+
+export function getCurrentTopic(
+    config: StarlightSidebarTopicsDropdownSharedConfig,
+    sidebar: SidebarEntry[],
+    currentSlug: string
+): Topic | undefined {
+    // 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;
+
+    return { config: currentTopicConfig, sidebar: currentSidebarTopic.entries };
+}
+
+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;
+
+    // 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;
+            }
+
+            break;
+        }
+    }
+
+    if (!topicConfig || !topicSidebar) return;
+
+    return { config: topicConfig, sidebar: topicSidebar };
+}
+
+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);
+    });
+}
+
+type SidebarEntry = Props["sidebar"][number];
+
+interface SidebarTopic {
+    label: string;
+    entries: SidebarEntry[];
+}
+
+interface Topic {
+    config: StarlightSidebarTopicsDropdownSharedConfig[number];
+    sidebar: SidebarEntry[];
+}

package/lib/vite.ts

@@ -0,0 +1,34 @@
+import type { ViteUserConfig } from "astro";
+
+import type {
+    StarlightSidebarTopicsDropdownConfig,
+    StarlightSidebarTopicsDropdownSharedConfig,
+} from "./config";
+
+const moduleId = "virtual:starlight-sidebar-topics-dropdown/config";
+
+export function vitePluginStarlightSidebarTopicsDropdown(
+    config: StarlightSidebarTopicsDropdownConfig
+): VitePlugin {
+    const resolvedModuleId = `\0${moduleId}`;
+
+    const sharedConfig: StarlightSidebarTopicsDropdownSharedConfig = config.map((topic) => {
+        if (!("items" in topic)) return { ...topic, type: "link" };
+        const { items, ...topicWithoutItems } = topic;
+        return { ...topicWithoutItems, type: "group" };
+    });
+
+    const moduleContent = `export default ${JSON.stringify(sharedConfig)}`;
+
+    return {
+        name: "vite-plugin-starlight-sidebar-topics-dropdown",
+        load(id) {
+            return id === resolvedModuleId ? moduleContent : undefined;
+        },
+        resolveId(id) {
+            return id === moduleId ? resolvedModuleId : undefined;
+        },
+    };
+}
+
+type VitePlugin = NonNullable<ViteUserConfig["plugins"]>[number];

package/overrides/Pagination.astro

@@ -0,0 +1,19 @@
+---
+import Default from '@astrojs/starlight/components/Pagination.astro'
+import type { Props } from '@astrojs/starlight/props'
+
+import { isTopicFirstPage, isTopicLastPage } from '../lib/sidebar'
+
+const { pagination, sidebar, slug } = Astro.props
+let { prev, next } = pagination
+
+if (isTopicFirstPage(sidebar, slug)) {
+  prev = undefined
+}
+
+if (isTopicLastPage(sidebar, slug)) {
+  next = undefined
+}
+---
+
+<Default {...Astro.props} pagination={{ prev, next }}><slot /></Default>

package/overrides/Sidebar.astro

@@ -0,0 +1,22 @@
+---
+import Default from '@astrojs/starlight/components/Sidebar.astro'
+import type { Props } from '@astrojs/starlight/props'
+import config from 'virtual:starlight-sidebar-topics-dropdown/config'
+
+import Topics from '../components/Topics.astro'
+import { throwPluginError } from '../lib/plugin'
+import { getCurrentTopic } from '../lib/sidebar'
+
+const { entry, sidebar, slug } = Astro.props
+
+let currentSidebar = sidebar
+const currentTopic = getCurrentTopic(config, sidebar, slug)
+
+if (entry['data'].template !== 'splash') {
+  if (!currentTopic) throwPluginError('Failed to find the topic for the current page.')
+  currentSidebar = currentTopic.sidebar
+}
+---
+
+{entry['data'].template !== 'splash' && currentTopic && <Topics current={currentTopic.config} />}
+<Default {...Astro.props} sidebar={currentSidebar}><slot /></Default>

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "starlight-sidebar-topics-dropdown",
+    "version": "0.1.0",
+    "license": "MIT",
+    "description": "Starlight plugin to split your docs page into multiple subpages and switch between them with a dropdown menu in the sidebar.",
+    "author": "trueberryless (https://trueberryless.org)",
+    "type": "module",
+    "exports": {
+        ".": "./index.ts",
+        "./overrides/Pagination.astro": "./overrides/Pagination.astro",
+        "./overrides/Sidebar.astro": "./overrides/Sidebar.astro",
+        "./package.json": "./package.json"
+    },
+    "devDependencies": {
+        "@astrojs/starlight": "^0.28.3",
+        "astro": "^4.16.6"
+    },
+    "peerDependencies": {
+        "@astrojs/starlight": ">=0.28"
+    },
+    "engines": {
+        "node": "^18.17.1 || ^20.3.0 || >=21.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "starlight",
+        "plugin",
+        "sidebar",
+        "subpages",
+        "sections",
+        "dropdown",
+        "documentation",
+        "astro"
+    ],
+    "homepage": "https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown.git",
+        "directory": "packages/starlight-sidebar-topics-dropdown"
+    },
+    "bugs": "https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/issues"
+}

package/starlight.d.ts

@@ -0,0 +1,5 @@
+declare module "virtual:starlight/user-config" {
+    const Config: import("@astrojs/starlight/types").StarlightConfig;
+
+    export default Config;
+}

package/virtual.d.ts

@@ -0,0 +1,5 @@
+declare module "virtual:starlight-sidebar-topics-dropdown/config" {
+    const StarlightSidebarTopicsDropdownConfig: import("./libs/config").StarlightSidebarTopicsDropdownSharedConfig;
+
+    export default StarlightSidebarTopicsDropdownConfig;
+}