starlight-sidebar-topics-dropdown 0.1.0 → 0.2.0

package/lib/config.ts

@@ -43,6 +43,11 @@ const sidebarTopicBaseSchema = z.object({
 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.
      *

package/lib/content.ts

@@ -0,0 +1,11 @@
+import type { Props } from "@astrojs/starlight/props";
+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 = Props["entry"];
+export type StarlightEntryWithTopic = StarlightEntry & { data: TopicFrontmatterSchema };

package/lib/sidebar.ts

@@ -1,6 +1,7 @@
 import type { Props } from "@astrojs/starlight/props";
 
 import type { StarlightSidebarTopicsDropdownSharedConfig } from "./config";
+import { isStarlightEntryWithTopic, type StarlightEntry } from "./content";
 import { getLocaleFromSlug, getLocalizedSlug } from "./i18n";
 import { arePathnamesEqual, stripLeadingAndTrailingSlashes } from "./pathname";
 
@@ -9,8 +10,13 @@ const absoluteLinkRegex = /^https?:\/\//;
 export function getCurrentTopic(
     config: StarlightSidebarTopicsDropdownSharedConfig,
     sidebar: SidebarEntry[],
-    currentSlug: string
+    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;
@@ -100,6 +106,29 @@ function getTopicFromSlug(
     return { config: topicConfig, sidebar: topicSidebar };
 }
 
+function getTopicById(
+    config: StarlightSidebarTopicsDropdownSharedConfig,
+    sidebar: SidebarEntry[],
+    id: string
+): Topic | undefined {
+    let topicConfig: Topic["config"] | undefined;
+    let topicSidebar: Topic["sidebar"] | undefined;
+    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;
+            }
+            break;
+        }
+    }
+    if (!topicConfig || !topicSidebar) return;
+    return { config: topicConfig, sidebar: topicSidebar };
+}
+
 function getCurrentSidebarTopic(sidebar: SidebarEntry[]): SidebarTopic | undefined {
     let currentSidebarTopic: SidebarTopic | undefined;
 
@@ -127,6 +156,10 @@ function getCurrentSidebarEntry(sidebar: SidebarEntry[]): SidebarEntry | undefin
     });
 }
 
+function getTopicIdFromEntry(entry: StarlightEntry): string | undefined {
+    return isStarlightEntryWithTopic(entry) ? entry.data.topic : undefined;
+}
+
 type SidebarEntry = Props["sidebar"][number];
 
 interface SidebarTopic {
@@ -134,7 +167,7 @@ interface SidebarTopic {
     entries: SidebarEntry[];
 }
 
-interface Topic {
+export interface Topic {
     config: StarlightSidebarTopicsDropdownSharedConfig[number];
     sidebar: SidebarEntry[];
 }

package/overrides/Sidebar.astro

@@ -5,15 +5,21 @@ 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'
+import { getCurrentTopic, type Topic } from '../lib/sidebar'
 
 const { entry, sidebar, slug } = Astro.props
 
 let currentSidebar = sidebar
-const currentTopic = getCurrentTopic(config, sidebar, slug)
+let currentTopic: Topic | undefined = undefined
 
 if (entry['data'].template !== 'splash') {
-  if (!currentTopic) throwPluginError('Failed to find the topic for the current page.')
+  currentTopic = getCurrentTopic(config, sidebar, slug, entry)
+  if (!currentTopic)
+    throwPluginError(
+      'Failed to find the topic for the current page.',
+      `Either include the 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.
+Learn more about unlisted pages in the ["Unlisted pages"](https://starlight-sidebar-topics.netlify.app/docs/guides/unlisted-pages/) guide.`,
+    )
   currentSidebar = currentTopic.sidebar
 }
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "starlight-sidebar-topics-dropdown",
-    "version": "0.1.0",
+    "version": "0.2.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)",
@@ -9,6 +9,7 @@
         ".": "./index.ts",
         "./overrides/Pagination.astro": "./overrides/Pagination.astro",
         "./overrides/Sidebar.astro": "./overrides/Sidebar.astro",
+        "./schema": "./schema.ts",
         "./package.json": "./package.json"
     },
     "devDependencies": {
@@ -21,6 +22,7 @@
     "engines": {
         "node": "^18.17.1 || ^20.3.0 || >=21.0.0"
     },
+    "packageManager": "pnpm@9.3.0",
     "publishConfig": {
         "access": "public"
     },

package/schema.ts

@@ -0,0 +1,10 @@
+import { z } from "astro/zod";
+export const topicSchema = z.object({
+    /**
+     * ID of the topic to associate with the current page if the page is not listed in any topic sidebar configuration.
+     *
+     * @see https://starlight-sidebar-topics.netlify.app/docs/guides/unlisted-pages/
+     */
+    topic: z.string().optional(),
+});
+export type TopicFrontmatterSchema = z.input<typeof topicSchema>;