starlight-cannoli-plugins 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# Cannoli Starlight Plugins
+
+A collection of powerful plugins for [Astro Starlight](https://starlight.astro.build/) documentation sites.
+
+## Plugins
+
+### Starlight Index-Only Sidebar
+
+Automatically generates your Starlight sidebar by scanning for `index.md` files in specified directories. Only directories containing an `index.md` file will appear in the sidebar.
+
+**Features:**
+- Scans directories recursively for `index.md` files
+- Respects frontmatter: `draft: true` and `sidebar.hidden: true` hide entries
+- Option to use directory names as sidebar labels with automatic formatting (e.g., `csci-316` → `CSCI 316`)
+- No manual sidebar configuration needed
+
+**Usage:**
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import { starlightIndexOnlySidebar } from "cannoli-starlight-plugins";
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: "My Docs",
+      plugins: [
+        starlightIndexOnlySidebar({
+          directories: [
+            { label: "Guides", directory: "guides" },
+            { label: "API Docs", directory: "api" },
+          ],
+          dirnameDeterminesLabel: false, // optional: use directory names as labels
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+### Rehype Validate Links
+
+A rehype plugin that validates all internal links in your Markdown/MDX files at build time. Links without matching files will cause the build to fail.
+
+**Features:**
+- Validates `<a href>` and `<img src>` attributes
+- Supports relative paths (`../other`) and absolute paths (`/some/page`)
+- Auto-expands extensionless links to match `.md` or `.mdx` files
+- Converts internal links to site-absolute paths
+- Throws build errors for broken links
+
+**Usage:**
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import { rehypeValidateLinks } from "cannoli-starlight-plugins";
+
+export default defineConfig({
+  markdown: {
+    rehypePlugins: [
+      rehypeValidateLinks,
+    ],
+  },
+});
+```
+
+Or import directly:
+
+```ts
+import { rehypeValidateLinks } from "cannoli-starlight-plugins/rehype-validate-links";
+```
+
+## Installation
+
+```bash
+npm install cannoli-starlight-plugins
+```
+
+With pnpm:
+
+```bash
+pnpm add cannoli-starlight-plugins
+```
+
+With yarn:
+
+```bash
+yarn add cannoli-starlight-plugins
+```
+
+## Peer Dependencies
+
+- `astro` ≥ 5.0.0
+- `@astrojs/starlight` ≥ 0.30.0 (optional, only needed if using `starlightIndexOnlySidebar`)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Feel free to open issues or submit pull requests.

package/dist/chunk-6XXMT37V.js

@@ -0,0 +1,162 @@
+// src/plugins/starlight-index-only-sidebar.ts
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+var SITE_DOCS_ROOT = "./src/content/docs";
+function getFrontmatterMetadata(mdFilePath) {
+  const defaultMetadata = {
+    title: null,
+    draft: false,
+    sidebarHidden: false
+  };
+  try {
+    const content = readFileSync(mdFilePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return defaultMetadata;
+    const frontmatterText = match[1];
+    const frontmatter = parseYaml(frontmatterText);
+    if (!frontmatter || typeof frontmatter !== "object") {
+      return defaultMetadata;
+    }
+    const title = typeof frontmatter.title === "string" ? frontmatter.title : null;
+    const draft = frontmatter.draft === true;
+    let sidebarHidden = false;
+    if (frontmatter.sidebar) {
+      if (typeof frontmatter.sidebar === "object" && frontmatter.sidebar !== null) {
+        sidebarHidden = frontmatter.sidebar.hidden === true;
+      }
+    }
+    return {
+      title,
+      draft,
+      sidebarHidden
+    };
+  } catch {
+    return defaultMetadata;
+  }
+}
+function pathSegmentToLabel(pathSegment) {
+  let label = pathSegment.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  const match = label.match(/^([a-z]+) [0-9]{2,}/i);
+  if (match) {
+    const firstGroup = match[1];
+    const uppercasedFirstGroup = firstGroup.toUpperCase();
+    label = uppercasedFirstGroup + label.substring(firstGroup.length);
+  }
+  return label;
+}
+function processRootIndex(dir, basePath, dirDeterminesLabel, items) {
+  if (!basePath || basePath.includes("/")) {
+    return;
+  }
+  const indexPath = join(dir, "index.md");
+  try {
+    statSync(indexPath);
+  } catch {
+    return;
+  }
+  const metadata = getFrontmatterMetadata(indexPath);
+  if (metadata.draft || metadata.sidebarHidden) {
+    return;
+  }
+  if (dirDeterminesLabel) {
+    const lastSegment = basePath.split("/").pop() || basePath;
+    items.push({
+      label: pathSegmentToLabel(lastSegment),
+      slug: basePath
+    });
+  } else {
+    items.push(basePath);
+  }
+}
+function buildIndexSidebar(dir, basePath = "", docsRoot, dirDeterminesLabel = false) {
+  const items = [];
+  try {
+    processRootIndex(dir, basePath, dirDeterminesLabel, items);
+    const entries = readdirSync(dir).sort();
+    for (const entry of entries) {
+      if (entry.startsWith(".")) continue;
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        const indexPath = join(fullPath, "index.md");
+        const slug = basePath ? `${basePath}/${entry}` : entry;
+        try {
+          statSync(indexPath);
+          const metadata = getFrontmatterMetadata(indexPath);
+          if (metadata.draft || metadata.sidebarHidden) {
+            continue;
+          }
+          const subItems = buildIndexSidebar(fullPath, slug, docsRoot, dirDeterminesLabel);
+          if (subItems.length > 0) {
+            let groupLabel;
+            if (dirDeterminesLabel) {
+              groupLabel = pathSegmentToLabel(entry);
+            } else {
+              const title = metadata.title || entry;
+              groupLabel = title;
+            }
+            items.push({
+              label: groupLabel,
+              items: [dirDeterminesLabel ? { label: groupLabel, slug } : slug, ...subItems]
+            });
+          } else {
+            if (dirDeterminesLabel) {
+              items.push({
+                label: pathSegmentToLabel(entry),
+                slug
+              });
+            } else {
+              items.push(slug);
+            }
+          }
+        } catch {
+          const subItems = buildIndexSidebar(fullPath, slug, docsRoot, dirDeterminesLabel);
+          if (subItems.length > 0) {
+            items.push(...subItems);
+          }
+        }
+      }
+    }
+  } catch (error) {
+    console.error(`Error reading directory ${dir}:`, error);
+  }
+  return items.sort((a, b) => {
+    const aIsGroup = typeof a === "object" && "items" in a;
+    const bIsGroup = typeof b === "object" && "items" in b;
+    if (!aIsGroup && bIsGroup) return -1;
+    if (aIsGroup && !bIsGroup) return 1;
+    return 0;
+  });
+}
+function starlightIndexOnlySidebar(options) {
+  return {
+    name: "index-only-sidebar",
+    hooks: {
+      "config:setup": (hookOptions) => {
+        const { updateConfig } = hookOptions;
+        const dirnameDeterminesLabel = options.dirnameDeterminesLabel ?? false;
+        const sidebarItems = options.directories.map((dirConfig) => {
+          const dirItems = buildIndexSidebar(
+            join(SITE_DOCS_ROOT, dirConfig.directory),
+            dirConfig.directory,
+            SITE_DOCS_ROOT,
+            dirnameDeterminesLabel
+          );
+          const label = dirnameDeterminesLabel ? pathSegmentToLabel(dirConfig.directory) : dirConfig.label;
+          return {
+            label,
+            items: dirItems
+          };
+        }).filter((group) => group.items.length > 0);
+        updateConfig({
+          sidebar: sidebarItems
+        });
+      }
+    }
+  };
+}
+
+export {
+  starlightIndexOnlySidebar
+};

package/dist/chunk-WOOF7XZX.js

@@ -0,0 +1,109 @@
+// src/plugins/rehype-validate-links.ts
+import { existsSync } from "fs";
+import { sync as globSync } from "glob";
+import { dirname, join, relative, resolve } from "path";
+import { visit } from "unist-util-visit";
+var PROJECT_DOCS_DIR = "src/content/docs";
+function getResolvedLink(href, currentFilePath) {
+  try {
+    new URL(href);
+    return null;
+  } catch {
+  }
+  if (!href) {
+    return null;
+  }
+  const fragmentMatch = href.split("#");
+  const withoutFragment = fragmentMatch[0];
+  const fragment = fragmentMatch[1] || "";
+  if (!withoutFragment) {
+    return null;
+  }
+  let projectAbsolute;
+  let relativePath;
+  if (withoutFragment.startsWith("/")) {
+    relativePath = withoutFragment.slice(1);
+    projectAbsolute = join(PROJECT_DOCS_DIR, relativePath);
+  } else {
+    const currentFileDir = dirname(currentFilePath);
+    const resolvedAbsPath = resolve(currentFileDir, withoutFragment);
+    projectAbsolute = resolvedAbsPath;
+    const docsRootAbsolute = resolve(PROJECT_DOCS_DIR);
+    relativePath = relative(docsRootAbsolute, resolvedAbsPath);
+  }
+  const hasExtension = /\.[a-z0-9]+$/i.test(projectAbsolute);
+  let finalProjectAbsoluteHref;
+  if (!hasExtension) {
+    finalProjectAbsoluteHref = `${projectAbsolute}.{md,mdx}`;
+  } else {
+    finalProjectAbsoluteHref = projectAbsolute;
+  }
+  let siteAbsoluteHref = "/" + relativePath;
+  if (fragment) {
+    siteAbsoluteHref += "#" + fragment;
+  }
+  return {
+    original_href: href,
+    project_absolute_href: finalProjectAbsoluteHref,
+    site_absolute_href: siteAbsoluteHref,
+    fragment
+  };
+}
+function validateLink(link) {
+  const { project_absolute_href } = link;
+  if (project_absolute_href.includes(".{md,mdx}")) {
+    const matches = globSync(project_absolute_href);
+    if (matches.length === 0) {
+      throw new Error(
+        `Link validation error: No matching file found for: ${link.original_href} (pattern: ${project_absolute_href})`
+      );
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `Link validation error: Multiple matching files found: ${matches.join(
+          ", "
+        )} (from link: ${link.original_href})`
+      );
+    }
+  } else {
+    if (!existsSync(project_absolute_href)) {
+      throw new Error(
+        `Link validation error: File not found: ${project_absolute_href} (from link: ${link.original_href})`
+      );
+    }
+  }
+}
+function rehypeValidateLinks() {
+  return (tree, file) => {
+    const filePath = file.path;
+    if (!filePath) {
+      console.warn(
+        "rehype-validate-links: Unable to determine file path for link validation. Skipping link validation for this file."
+      );
+      return;
+    }
+    visit(tree, "element", (node) => {
+      let resourcePath;
+      let attributeName = null;
+      if (node.tagName === "a") {
+        resourcePath = node.properties?.href;
+        attributeName = "href";
+      } else if (node.tagName === "img") {
+        resourcePath = node.properties?.src;
+        attributeName = "src";
+      }
+      if (!resourcePath || !attributeName) return;
+      const link = getResolvedLink(resourcePath, filePath);
+      if (!link) return;
+      validateLink(link);
+      node.properties = node.properties || {};
+      node.properties[attributeName] = link.site_absolute_href;
+    });
+  };
+}
+var rehype_validate_links_default = rehypeValidateLinks;
+
+export {
+  rehypeValidateLinks,
+  rehype_validate_links_default
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { starlightIndexOnlySidebar } from './plugins/starlight-index-only-sidebar.js';
+export { default as rehypeValidateLinks } from './plugins/rehype-validate-links.js';
+import '@astrojs/starlight/types';
+import 'hast';
+import 'vfile';

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  starlightIndexOnlySidebar
+} from "./chunk-6XXMT37V.js";
+import {
+  rehypeValidateLinks
+} from "./chunk-WOOF7XZX.js";
+export {
+  rehypeValidateLinks,
+  starlightIndexOnlySidebar
+};

package/dist/plugins/rehype-validate-links.d.ts

@@ -0,0 +1,9 @@
+import { Root } from 'hast';
+import { VFile } from 'vfile';
+
+/**
+ * Rehype plugin to validate all internal links and convert them to absolute paths
+ */
+declare function rehypeValidateLinks(): (tree: Root, file: VFile) => void;
+
+export { rehypeValidateLinks as default, rehypeValidateLinks };

package/dist/plugins/rehype-validate-links.js

@@ -0,0 +1,8 @@
+import {
+  rehypeValidateLinks,
+  rehype_validate_links_default
+} from "../chunk-WOOF7XZX.js";
+export {
+  rehype_validate_links_default as default,
+  rehypeValidateLinks
+};

package/dist/plugins/starlight-index-only-sidebar.d.ts

@@ -0,0 +1,18 @@
+import { HookParameters } from '@astrojs/starlight/types';
+
+type TDirectoryConfig = {
+    label: string;
+    directory: string;
+};
+type TIndexOnlySidebarPluginOptions = {
+    directories: Array<TDirectoryConfig>;
+    dirnameDeterminesLabel?: boolean;
+};
+declare function starlightIndexOnlySidebar(options: TIndexOnlySidebarPluginOptions): {
+    name: string;
+    hooks: {
+        "config:setup": (hookOptions: HookParameters<"config:setup">) => void;
+    };
+};
+
+export { starlightIndexOnlySidebar };

package/dist/plugins/starlight-index-only-sidebar.js

@@ -0,0 +1,6 @@
+import {
+  starlightIndexOnlySidebar
+} from "../chunk-6XXMT37V.js";
+export {
+  starlightIndexOnlySidebar
+};

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "starlight-cannoli-plugins",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Starlight plugins for automatic sidebar generation and link validation",
+  "license": "ISC",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./starlight-index-only-sidebar": {
+      "import": "./dist/plugins/starlight-index-only-sidebar.js",
+      "types": "./dist/plugins/starlight-index-only-sidebar.d.ts"
+    },
+    "./rehype-validate-links": {
+      "import": "./dist/plugins/rehype-validate-links.js",
+      "types": "./dist/plugins/rehype-validate-links.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "astro",
+    "starlight",
+    "plugin",
+    "sidebar",
+    "rehype",
+    "link-validation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OccasionalCoderByTrade/astro-starlight-plugins"
+  },
+  "scripts": {
+    "build:lib": "tsup",
+    "dev": "node scripts/sync-docs-to-public.js && astro dev --port 5600",
+    "build": "npm run build:lib && node scripts/sync-docs-to-public.js && astro build",
+    "preview": "astro build && astro preview --port 5600",
+    "help": "astro --help",
+    "check": "astro check",
+    "prepublishOnly": "npm run build:lib"
+  },
+  "dependencies": {
+    "glob": "^13.0.6",
+    "unist-util-visit": "^5.0.0",
+    "yaml": "^2.4.0"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.30.0",
+    "astro": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": false
+    },
+    "@astrojs/starlight": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.6",
+    "@astrojs/starlight": "^0.37.6",
+    "@expressive-code/plugin-line-numbers": "^0.41.7",
+    "@hpcc-js/wasm": "^2.33.1",
+    "@types/hast": "^2.3.10",
+    "astro": "^5.6.1",
+    "hast": "^1.0.0",
+    "rehype-graphviz": "^0.3.0",
+    "rehype-mathjax": "^7.1.0",
+    "rehype-raw": "^7.0.0",
+    "remark-math": "^6.0.0",
+    "sharp": "^0.34.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vfile": "^6.0.0",
+    "@eslint/js": "^10.0.1",
+    "@eslint/markdown": "^7.5.1",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^10.0.2",
+    "eslint-md-cannoli-plugins": "^1.0.2",
+    "globals": "^17.4.0",
+    "jiti": "^2.6.1",
+    "sass-embedded": "^1.97.3",
+    "typescript-eslint": "^8.56.1"
+  }
+}