starlight-cannoli-plugins 2.7.0 → 2.8.0

package/README.md

@@ -399,6 +399,7 @@ An Astro integration that injects a client-side script to apply opt-in DOM patch
 - `hideSingleLineGutters` (optional, default: `false`): Hides the line number gutter on Expressive Code blocks that contain only a single line.
 - `syncTocLabelsFromHeadings` (optional, default: `false`): Copies the rendered HTML of each heading into its matching Starlight TOC anchor label, so the TOC properly reflects any custom markup (e.g. math) present in the heading.
 - `wrapDetailsContent` (optional, default: `false`): Wraps the content of every `<details>` element (excluding its `<summary>`) in a `<div class="details-wrapper">`, useful for applying consistent spacing or animation styles.
+- `offerTabbedContent` (optional, default: `false`): Injects a "Tabbed view" toggle checkbox immediately after `#starlight__on-this-page` in the right sidebar. When enabled by the user, the page's markdown content is reorganised into tabs — one per `<h2>` heading, plus an optional "Main" tab for any content that appears before the first `<h2>`. The toggle state is persisted to `localStorage`; active tab selection is not persisted. Only activates when the page has at least two sections (i.e. two or more `<h2>` elements, or one `<h2>` with pre-heading content). Has no effect on pages that lack `#starlight__on-this-page` (e.g. pages with the TOC disabled). Clicking a TOC anchor while tabs are enabled automatically switches to the tab containing the target heading. The generated elements use the classes `tabbed-content`, `tabbed-content-nav`, `tabbed-content-tab`, and `tabbed-content-panel` for styling; toggle button uses the existing `.toggle-checkbox-btn` class.
 
 **Usage:**
 
@@ -414,6 +415,7 @@ export default defineConfig({
       hideSingleLineGutters: true,
       syncTocLabelsFromHeadings: true,
       wrapDetailsContent: true,
+      offerTabbedContent: true,
     }),
     starlight({ title: "My Docs" }),
   ],

package/dist/{chunk-XMGAWBJ5.js → chunk-OXJMUUGP.js}

@@ -4,7 +4,8 @@ function starlightDomPatches(options = {}) {
   const {
     hideSingleLineGutters = false,
     syncTocLabelsFromHeadings = false,
-    wrapDetailsContent = false
+    wrapDetailsContent = false,
+    offerTabbedContent = false
   } = options;
   return {
     name: "starlight-dom-patches",
@@ -29,7 +30,8 @@ function starlightDomPatches(options = {}) {
         const imports = [
           hideSingleLineGutters ? "hideSingleLineGutters" : null,
           syncTocLabelsFromHeadings ? "syncTocLabelsFromHeadings" : null,
-          wrapDetailsContent ? "wrapDetailsContent" : null
+          wrapDetailsContent ? "wrapDetailsContent" : null,
+          offerTabbedContent ? "tabbedH2Content" : null
         ].filter(Boolean);
         if (imports.length === 0) return;
         const calls = imports.map((fn) => `${fn}();`).join("\n");

package/dist/index.d.ts

@@ -13,6 +13,12 @@ import 'vfile';
 import 'mdast';
 import 'expressive-code';
 
+type TBadgeVariant = "note" | "danger" | "success" | "caution" | "tip" | "default";
+type TIndexMarker = {
+    text: string;
+    variant: TBadgeVariant;
+};
+
 type TOptions = {
     /**
      * Controls how deep the nested group structure can go, where the root directory is level 0.
@@ -32,7 +38,13 @@ type TOptions = {
      * regular sidebar entries. When undefined, no marker is added.
      * @example "★"
      */
-    indexMarker?: string;
+    indexMarker?: TIndexMarker;
+    /**
+     * Whether sidebar groups should be collapsed by default. Starlight automatically expands
+     * the group containing the current page regardless of this setting.
+     * @default true
+     */
+    collapsed?: boolean;
 };
 /**
  * Starlight plugin that generates a sidebar by parsing markdown links from index.md files.

package/dist/index.js

@@ -24,7 +24,7 @@ import {
 } from "./chunk-NCXV367P.js";
 import {
   starlightDomPatches
-} from "./chunk-XMGAWBJ5.js";
+} from "./chunk-OXJMUUGP.js";
 import "./chunk-4VNS5WPM.js";
 
 // src/plugins/starlight-index-sourced-sidebar/index.ts
@@ -110,7 +110,7 @@ function tryResolveMarkdownFile(href, currentDir) {
   }
   return findMarkdownFile(resolved);
 }
-function buildItems(dirPath, currentDepth, maxDepth, visited, indexMarker) {
+function buildItems(dirPath, currentDepth, maxDepth, visited, indexMarker, collapsed) {
   const absDir = path.resolve(dirPath);
   if (visited.has(absDir)) return [];
   visited.add(absDir);
@@ -125,8 +125,9 @@ function buildItems(dirPath, currentDepth, maxDepth, visited, indexMarker) {
   const items = [];
   const indexBaseLabel = fm.title ?? pathSegmentToLabel(path.basename(absDir));
   items.push({
-    label: indexMarker ? `${indexMarker} ${indexBaseLabel}` : indexBaseLabel,
-    slug: normalizeSlug(filePathToSlug(indexFile))
+    label: indexBaseLabel,
+    slug: normalizeSlug(filePathToSlug(indexFile)),
+    ...indexMarker && { badge: indexMarker }
   });
   for (const href of extractMarkdownLinks(indexFile)) {
     if (isExternal(href)) continue;
@@ -143,8 +144,9 @@ function buildItems(dirPath, currentDepth, maxDepth, visited, indexMarker) {
           continue;
         const subBaseLabel = subFm.title ?? pathSegmentToLabel(path.basename(subDirPath));
         items.push({
-          label: indexMarker ? `${indexMarker} ${subBaseLabel}` : subBaseLabel,
-          slug: normalizeSlug(filePathToSlug(resolvedFile))
+          label: subBaseLabel,
+          slug: normalizeSlug(filePathToSlug(resolvedFile)),
+          ...indexMarker && { badge: indexMarker }
         });
       } else {
         const subItems = buildItems(
@@ -152,7 +154,8 @@ function buildItems(dirPath, currentDepth, maxDepth, visited, indexMarker) {
           currentDepth + 1,
           maxDepth,
           visited,
-          indexMarker
+          indexMarker,
+          collapsed
         );
         if (subItems.length === 0) continue;
         if (currentDepth + 1 >= maxDepth) {
@@ -160,7 +163,8 @@ function buildItems(dirPath, currentDepth, maxDepth, visited, indexMarker) {
         } else {
           items.push({
             label: pathSegmentToLabel(path.basename(subDirPath)),
-            items: subItems
+            items: subItems,
+            collapsed
           });
         }
       }
@@ -178,7 +182,7 @@ function buildItems(dirPath, currentDepth, maxDepth, visited, indexMarker) {
   }
   return items;
 }
-function getIndexSourcedSidebarItems(directory, maxDepthNesting = 100, indexMarker) {
+function getIndexSourcedSidebarItems(directory, maxDepthNesting = 100, indexMarker, collapsed = true) {
   const absDir = path.resolve(directory);
   const rootGroupLabel = pathSegmentToLabel(path.basename(absDir));
   const items = buildItems(
@@ -186,10 +190,11 @@ function getIndexSourcedSidebarItems(directory, maxDepthNesting = 100, indexMark
     0,
     maxDepthNesting,
     /* @__PURE__ */ new Set(),
-    indexMarker
+    indexMarker,
+    collapsed
   );
   if (items.length === 0) return [];
-  return [{ label: rootGroupLabel, items }];
+  return [{ label: rootGroupLabel, items, collapsed }];
 }
 
 // src/plugins/starlight-index-sourced-sidebar/index.ts
@@ -200,13 +205,14 @@ function starlightIndexSourcedSidebar(options) {
     hooks: {
       "config:setup": (hookOptions) => {
         const { updateConfig } = hookOptions;
-        const { directories, maxDepthNesting = 100, indexMarker } = options;
+        const { directories, maxDepthNesting = 100, indexMarker, collapsed = true } = options;
         const sidebarItems = directories.map((directory) => {
           const dirPath = join2(SITE_DOCS_ROOT2, directory);
           const rawItems = getIndexSourcedSidebarItems(
             dirPath,
             maxDepthNesting,
-            indexMarker
+            indexMarker,
+            collapsed
           );
           const rootGroup = rawItems[0];
           if (!rootGroup || !("items" in rootGroup)) return void 0;

package/dist/plugins/starlight-dom-patches/page-script.d.ts

@@ -1,5 +1,6 @@
 declare function hideSingleLineGutters(): void;
 declare function syncTocLabelsFromHeadings(): void;
+declare function tabbedH2Content(): void;
 declare function wrapDetailsContent(): void;
 
-export { hideSingleLineGutters, syncTocLabelsFromHeadings, wrapDetailsContent };
+export { hideSingleLineGutters, syncTocLabelsFromHeadings, tabbedH2Content, wrapDetailsContent };

package/dist/plugins/starlight-dom-patches/page-script.js

@@ -16,6 +16,12 @@ function hideSingleLineGutters() {
     }
   });
 }
+function headingInnerHTML(heading) {
+  if (heading.childElementCount === 1 && heading.children[0].tagName === "STRONG") {
+    return heading.children[0].innerHTML;
+  }
+  return heading.innerHTML;
+}
 function syncTocLabelsFromHeadings() {
   document.querySelectorAll("starlight-toc ul li > a, mobile-starlight-toc ul li > a").forEach((anchor) => {
     const href = anchor.getAttribute("href") ?? "";
@@ -27,13 +33,152 @@ function syncTocLabelsFromHeadings() {
     if (!heading) return;
     const span = anchor.querySelector(":scope > span");
     if (!span) return;
-    span.innerHTML = heading.innerHTML;
+    span.innerHTML = headingInnerHTML(heading);
+  });
+}
+function tabbedH2Content() {
+  console.log("[tabbedH2Content] running");
+  const LS_KEY = "starlight-dom-patches:tabbed-content";
+  const container = document.querySelector(
+    ".main-pane .sl-markdown-content"
+  );
+  if (!container) {
+    console.log(
+      "[tabbedH2Content] no .main-pane .sl-markdown-content found \u2014 aborting"
+    );
+    return;
+  }
+  const tocSection = document.getElementById("starlight__on-this-page");
+  if (!tocSection) {
+    console.log(
+      "[tabbedH2Content] #starlight__on-this-page not found \u2014 aborting"
+    );
+    return;
+  }
+  const children = Array.from(container.children);
+  if (children.length === 0) {
+    console.log("[tabbedH2Content] content container is empty \u2014 aborting");
+    return;
+  }
+  console.log(`[tabbedH2Content] container element:`, container);
+  console.log(
+    `[tabbedH2Content] found ${children.length} children:`,
+    children.map((c) => c.tagName).join(", ")
+  );
+  const preH2Nodes = [];
+  const h2Sections = [];
+  let currentSection = null;
+  const isH2Wrapper = (el) => el.tagName === "DIV" && el.classList.contains("sl-heading-wrapper") && el.classList.contains("level-h2");
+  for (const child of children) {
+    if (isH2Wrapper(child)) {
+      if (currentSection) h2Sections.push(currentSection);
+      const h2 = child.querySelector("h2");
+      currentSection = {
+        label: h2 ? headingInnerHTML(h2) : "",
+        nodes: [child]
+      };
+    } else if (currentSection === null) {
+      preH2Nodes.push(child);
+    } else {
+      currentSection.nodes.push(child);
+    }
+  }
+  if (currentSection) h2Sections.push(currentSection);
+  const hasPreContent = preH2Nodes.length > 0;
+  const totalSections = (hasPreContent ? 1 : 0) + h2Sections.length;
+  console.log(
+    `[tabbedH2Content] preH2Nodes: ${preH2Nodes.length}, h2Sections: ${h2Sections.length}, totalSections: ${totalSections}`
+  );
+  if (totalSections <= 1) {
+    console.log(
+      "[tabbedH2Content] only one section \u2014 aborting (no tabs needed)"
+    );
+    return;
+  }
+  const allSections = [];
+  if (hasPreContent) allSections.push({ label: "Main", nodes: preH2Nodes });
+  allSections.push(...h2Sections);
+  const wrapper = document.createElement("div");
+  wrapper.className = "tabbed-content";
+  const nav = document.createElement("div");
+  nav.className = "tabbed-content-nav not-content";
+  const tabButtons = [];
+  const panels = [];
+  allSections.forEach((section, i) => {
+    const btn = document.createElement("button");
+    btn.className = "tabbed-content-tab";
+    btn.innerHTML = section.label;
+    btn.dataset.tab = String(i);
+    tabButtons.push(btn);
+    nav.appendChild(btn);
+    const panel = document.createElement("div");
+    panel.className = "tabbed-content-panel";
+    panel.dataset.panel = String(i);
+    section.nodes.forEach((node) => panel.appendChild(node));
+    panels.push(panel);
   });
-  document.querySelectorAll("starlight-toc ul > li > a > span").forEach((span) => {
-    if (span.childElementCount !== 1) return;
-    const child = span.children[0];
-    if (child.tagName !== "STRONG") return;
-    span.innerHTML = child.innerHTML;
+  wrapper.appendChild(nav);
+  panels.forEach((p) => wrapper.appendChild(p));
+  container.appendChild(wrapper);
+  let activeTab = 0;
+  function activateTab(index) {
+    activeTab = index;
+    tabButtons.forEach((btn, i) => {
+      btn.dataset.active = String(i === index);
+    });
+    panels.forEach((panel, i) => {
+      panel.hidden = i !== index;
+    });
+  }
+  function setEnabled(enabled) {
+    wrapper.dataset.enabled = String(enabled);
+    nav.hidden = !enabled;
+    if (enabled) {
+      activateTab(activeTab);
+    } else {
+      panels.forEach((panel) => {
+        panel.hidden = false;
+      });
+    }
+  }
+  tabButtons.forEach((btn, i) => {
+    btn.addEventListener("click", () => {
+      if (wrapper.dataset.enabled === "true") activateTab(i);
+    });
+  });
+  function navigateToHash(hash) {
+    if (!hash || wrapper.dataset.enabled !== "true") return;
+    const id = hash.startsWith("#") ? hash.slice(1) : hash;
+    panels.forEach((panel, i) => {
+      if (panel.querySelector(`#${CSS.escape(id)}`)) activateTab(i);
+    });
+  }
+  window.addEventListener(
+    "hashchange",
+    () => navigateToHash(window.location.hash)
+  );
+  if (window.location.hash) navigateToHash(window.location.hash);
+  const toggleLabel = document.createElement("label");
+  toggleLabel.className = "toggle-checkbox-btn";
+  const checkbox = document.createElement("input");
+  checkbox.type = "checkbox";
+  const toggleText = document.createElement("span");
+  toggleText.textContent = "Tabbed view";
+  toggleLabel.appendChild(checkbox);
+  toggleLabel.appendChild(toggleText);
+  tocSection.parentNode.insertBefore(toggleLabel, tocSection.nextSibling);
+  console.log(
+    "[tabbedH2Content] toggle checkbox injected after #starlight__on-this-page"
+  );
+  const initialEnabled = localStorage.getItem(LS_KEY) === "enabled";
+  console.log(
+    `[tabbedH2Content] localStorage value: ${localStorage.getItem(LS_KEY)}, initialEnabled: ${initialEnabled}`
+  );
+  checkbox.checked = initialEnabled;
+  setEnabled(initialEnabled);
+  checkbox.addEventListener("change", () => {
+    setEnabled(checkbox.checked);
+    localStorage.setItem(LS_KEY, checkbox.checked ? "enabled" : "disabled");
   });
 }
 function wrapDetailsContent() {
@@ -67,5 +212,6 @@ function wrapDetailsContent() {
 export {
   hideSingleLineGutters,
   syncTocLabelsFromHeadings,
+  tabbedH2Content,
   wrapDetailsContent
 };

package/dist/plugins/starlight-dom-patches.d.ts

@@ -7,6 +7,12 @@ interface DomPatchesOptions {
     syncTocLabelsFromHeadings?: boolean;
     /** Wrap `<details>` content (excluding `<summary>`) in a `.details-wrapper` div. @default false */
     wrapDetailsContent?: boolean;
+    /**
+     * Inject a toggle checkbox (after `#starlight__on-this-page`) that reorganises page content
+     * into tabs driven by `<h2>` boundaries. Toggle state is persisted to localStorage.
+     * @default false
+     */
+    offerTabbedContent?: boolean;
 }
 /**
  * Astro integration that injects a client-side script to apply DOM patches

package/dist/plugins/starlight-dom-patches.js

@@ -1,6 +1,6 @@
 import {
   starlightDomPatches
-} from "../chunk-XMGAWBJ5.js";
+} from "../chunk-OXJMUUGP.js";
 import "../chunk-4VNS5WPM.js";
 export {
   starlightDomPatches

package/dist/styles/_starlight.scss

@@ -133,6 +133,55 @@ div > div[class="page"] > svg {
   }
 }
 
+/********** Tabbed H2 Content **********/
+.tabbed-content-nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+  margin-bottom: 1.75rem;
+  max-height: 9rem;
+  overflow-y: auto;
+}
+
+.tabbed-content-tab {
+  padding: 0.3rem 0.85rem;
+  border: none;
+  border-radius: 9999px;
+  background-color: var(--sl-color-gray-6);
+  color: var(--sl-color-gray-3);
+  cursor: pointer;
+  font-size: 0.8125em;
+  font-weight: 500;
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease;
+
+  &:hover {
+    background-color: var(--sl-color-gray-5);
+    color: var(--sl-color-text);
+  }
+
+  &[data-active="true"] {
+    background-color: var(--sl-color-accent-high);
+    color: var(--sl-color-black);
+  }
+
+  html[data-theme="light"] & {
+    background-color: var(--sl-color-gray-7);
+    color: var(--sl-color-gray-4);
+
+    &:hover {
+      background-color: var(--sl-color-gray-6);
+      color: var(--sl-color-gray-2);
+    }
+
+    &[data-active="true"] {
+      background-color: var(--sl-color-accent-low);
+      color: var(--sl-color-white);
+    }
+  }
+}
+
 /********** Toggle Checkbox Styles **********/
 #toggle-all-details-btn {
   display: flex;
@@ -167,6 +216,39 @@ div > div[class="page"] > svg {
   }
 }
 
+.toggle-checkbox-btn {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  cursor: pointer;
+
+  input[type="checkbox"] {
+    position: relative;
+    appearance: none;
+    width: 1.2em;
+    height: 1.2em;
+    border: 2px solid currentColor;
+    border-radius: 2px;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: background-color 0.2s ease;
+
+    &:checked {
+      background-color: var(--sl-color-accent);
+      border-color: var(--sl-color-accent);
+
+      &::after {
+        content: "✓";
+        color: white;
+        font-size: 0.8em;
+        font-weight: bold;
+      }
+    }
+  }
+}
+
 // invert img.note-svg when on dark mode
 img.note-svg {
   padding-top: 1em;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-cannoli-plugins",
   "type": "module",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Starlight plugins for automatic sidebar generation and link validation",
   "license": "ISC",
   "main": "./dist/index.js",