starlight-cannoli-plugins 1.0.0 → 1.0.2

package/README.md

@@ -6,13 +6,22 @@ A collection of powerful plugins for [Astro Starlight](https://starlight.astro.b
 
 ### 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.
+Automatically generates a nested Starlight sidebar by recursively scanning directories for `index.md`/`index.mdx` files. Only directories with index files appear in the sidebar, creating a clean, minimal navigation structure.
 
 **Features:**
-- Scans directories recursively for `index.md` files
+- Recursively scans directories for `index.md` or `index.mdx` files
+- Creates sidebar entries only for pages with index 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
+- Automatically collapses single-child groups (no intermediate wrappers)
+- Configurable depth limiting to flatten deeply nested content
+- Two labeling modes: directory names or frontmatter titles
+- Ignores `assets` directories entirely
+
+**Options:**
+
+- `directories` (required): Array of directory names to scan (e.g., `["guides", "api"]`)
+- `maxDepthNesting` (optional, default: `100`): Maximum nesting depth. Root is level 0. At max depth, deeper index files are flattened as sibling items.
+- `dirnameDeterminesLabels` (optional, default: `true`): When `true`, all labels use raw directory names. When `false`, slug item labels come from frontmatter `title` field; group labels still use directory names.
 
 **Usage:**
 
@@ -28,11 +37,9 @@ export default defineConfig({
       title: "My Docs",
       plugins: [
         starlightIndexOnlySidebar({
-          directories: [
-            { label: "Guides", directory: "guides" },
-            { label: "API Docs", directory: "api" },
-          ],
-          dirnameDeterminesLabel: false, // optional: use directory names as labels
+          directories: ["guides", "api", "tutorials"],
+          maxDepthNesting: 2,           // optional
+          dirnameDeterminesLabels: false, // optional
         }),
       ],
     }),
@@ -50,6 +57,7 @@ A rehype plugin that validates all internal links in your Markdown/MDX files at
 - Auto-expands extensionless links to match `.md` or `.mdx` files
 - Converts internal links to site-absolute paths
 - Throws build errors for broken links
+- Skip validation for forward-reference links using multiple approaches
 
 **Usage:**
 
@@ -73,6 +81,48 @@ Or import directly:
 import { rehypeValidateLinks } from "cannoli-starlight-plugins/rehype-validate-links";
 ```
 
+**Skipping Link Validation:**
+
+There are three ways to skip validation for specific links:
+
+**1. Question Mark Prefix** (Per-link, in markdown)
+
+Prepend a `?` to the link href to skip validation:
+
+```mdx
+[Grade Calculator](?csci-320-331-obrenic/grade-calculator)
+[Grade Calculator](?./csci-320-331-obrenic/grade-calculator)
+[Grade Calculator](?/csci-320-331-obrenic/grade-calculator)
+```
+
+**2. HTML Data Attribute** (Per-link, requires HTML syntax)
+
+Use the `data-no-link-check` attribute on anchor tags:
+
+```mdx
+<a href="csci-320-331-obrenic/grade-calculator" data-no-link-check>Grade Calculator</a>
+```
+
+**3. Global Skip Patterns** (Configuration-based)
+
+Use the `skipPatterns` option to exclude links matching glob patterns:
+
+```ts
+// astro.config.mjs
+export default defineConfig({
+  markdown: {
+    rehypePlugins: [
+      [rehypeValidateLinks, {
+        skipPatterns: [
+          '/csci-320-331-obrenic/grade-calculator',  // exact match
+          '**/draft-*',                               // glob pattern
+        ]
+      }],
+    ],
+  },
+});
+```
+
 ## Installation
 
 ```bash

package/dist/{chunk-WOOF7XZX.js → chunk-TXRBCETT.js}

@@ -1,19 +1,32 @@
 // src/plugins/rehype-validate-links.ts
 import { existsSync } from "fs";
 import { sync as globSync } from "glob";
+import { minimatch } from "minimatch";
 import { dirname, join, relative, resolve } from "path";
 import { visit } from "unist-util-visit";
 var PROJECT_DOCS_DIR = "src/content/docs";
+function matchesSkipPattern(path, patterns) {
+  if (!patterns || patterns.length === 0) {
+    return false;
+  }
+  return patterns.some((pattern) => minimatch(path, pattern));
+}
 function getResolvedLink(href, currentFilePath) {
+  let skipValidation = false;
+  let processedHref = href;
+  if (href.startsWith("?")) {
+    skipValidation = true;
+    processedHref = href.slice(1);
+  }
   try {
-    new URL(href);
+    new URL(processedHref);
     return null;
   } catch {
   }
-  if (!href) {
+  if (!processedHref) {
     return null;
   }
-  const fragmentMatch = href.split("#");
+  const fragmentMatch = processedHref.split("#");
   const withoutFragment = fragmentMatch[0];
   const fragment = fragmentMatch[1] || "";
   if (!withoutFragment) {
@@ -46,7 +59,8 @@ function getResolvedLink(href, currentFilePath) {
     original_href: href,
     project_absolute_href: finalProjectAbsoluteHref,
     site_absolute_href: siteAbsoluteHref,
-    fragment
+    fragment,
+    skipValidation
   };
 }
 function validateLink(link) {
@@ -73,7 +87,7 @@ function validateLink(link) {
     }
   }
 }
-function rehypeValidateLinks() {
+function rehypeValidateLinks(options) {
   return (tree, file) => {
     const filePath = file.path;
     if (!filePath) {
@@ -82,7 +96,7 @@ function rehypeValidateLinks() {
       );
       return;
     }
-    visit(tree, "element", (node) => {
+    visit(tree, "element", (node, index, parent) => {
       let resourcePath;
       let attributeName = null;
       if (node.tagName === "a") {
@@ -95,6 +109,29 @@ function rehypeValidateLinks() {
       if (!resourcePath || !attributeName) return;
       const link = getResolvedLink(resourcePath, filePath);
       if (!link) return;
+      if (link.skipValidation) {
+        node.properties = node.properties || {};
+        node.properties[attributeName] = link.site_absolute_href;
+        return;
+      }
+      if (node.properties?.["data-no-link-check"] !== void 0) {
+        node.properties = node.properties || {};
+        node.properties[attributeName] = link.site_absolute_href;
+        return;
+      }
+      if (matchesSkipPattern(link.site_absolute_href, options?.skipPatterns)) {
+        node.properties = node.properties || {};
+        node.properties[attributeName] = link.site_absolute_href;
+        return;
+      }
+      if (index !== void 0 && parent && "children" in parent && Array.isArray(parent.children)) {
+        const nextNode = parent.children[index + 1];
+        if (nextNode && "type" in nextNode && nextNode.type === "comment" && "value" in nextNode && typeof nextNode.value === "string" && nextNode.value.includes("no-link-check")) {
+          node.properties = node.properties || {};
+          node.properties[attributeName] = link.site_absolute_href;
+          return;
+        }
+      }
       validateLink(link);
       node.properties = node.properties || {};
       node.properties[attributeName] = link.site_absolute_href;

package/dist/index.js

@@ -3,7 +3,7 @@ import {
 } from "./chunk-NTIYGHZG.js";
 import {
   rehypeValidateLinks
-} from "./chunk-WOOF7XZX.js";
+} from "./chunk-TXRBCETT.js";
 export {
   rehypeValidateLinks,
   starlightIndexOnlySidebar

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

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

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-cannoli-plugins",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Starlight plugins for automatic sidebar generation and link validation",
   "license": "ISC",
   "main": "./dist/index.js",
@@ -18,10 +18,13 @@
     "./rehype-validate-links": {
       "import": "./dist/plugins/rehype-validate-links.js",
       "types": "./dist/plugins/rehype-validate-links.d.ts"
-    }
+    },
+    "./styles": "./src/styles/",
+    "./styles/*": "./src/styles/*"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/styles"
   ],
   "keywords": [
     "astro",
@@ -49,6 +52,7 @@
   },
   "dependencies": {
     "glob": "^13.0.6",
+    "minimatch": "^10.2.4",
     "unist-util-visit": "^5.0.0",
     "yaml": "^2.4.0"
   },

package/src/styles/custom.scss

@@ -0,0 +1,393 @@
+$info-color: #3b82f6;
+$warning-color: #f59e0b;
+
+html {
+  scroll-behavior: smooth;
+}
+
+// invert img.note-svg when on dark mode
+img.note-svg {
+  color-scheme: light dark;
+  padding-top: 1em;
+  padding-bottom: 1em;
+
+  html[data-theme="light"] & {
+    filter: none;
+  }
+
+  html:not([data-theme="light"]) & {
+    filter: invert(1) hue-rotate(180deg);
+  }
+}
+
+/************ Starlight Additions/Overrides ************/
+
+.sl-container:where(.astro-7nkwcw3z) {
+  max-width: 50rem;
+}
+
+.main-pane {
+  table > thead > tr > th {
+    border-bottom: 1px solid hsl(228, 6.2%, 47.3%);
+  }
+}
+
+starlight-toc {
+  a {
+    transition: transform 0.2s ease;
+    transform-origin: left;
+
+    span {
+      position: relative;
+      display: inline-block;
+      transition: color 0.2s ease;
+
+      &::before {
+        content: "";
+        position: absolute;
+        left: -8px;
+        top: 0;
+        bottom: 0;
+        width: 3px;
+        background-color: transparent;
+        border-radius: 2px;
+        transition: background-color 0.2s ease;
+      }
+    }
+  }
+
+  a[aria-current="true"] {
+    transform: scale(1.04);
+
+    span {
+      &::before {
+        background-color: var(--sl-color-text-accent);
+      }
+    }
+  }
+}
+
+#starlight__search mark {
+  color: hsl(339.8, 63.4%, 60.4%);
+}
+
+#starlight__mobile-toc {
+  > .dropdown {
+    border-bottom: 1px solid hsla(0, 0%, 100%, 0.6);
+  }
+}
+
+.expressive-code .copy > button {
+  height: 2rem;
+  width: 2rem;
+}
+
+/************ Details/Summary Styles ************/
+.main-pane details {
+  background: var(--sl-color-bg-nav);
+  border-radius: 4px;
+  padding: 0.3rem 0.6rem;
+  display: block;
+
+  &[open] {
+    max-width: 100%;
+
+    > div.details-wrapper {
+      overflow: auto;
+      max-height: 67vh;
+      padding-right: 0.8rem;
+      padding-left: 0.8rem;
+    }
+
+    p > img {
+      height: auto;
+      width: auto;
+    }
+  }
+}
+
+/********** MathJax/LaTeX Styling **********/
+mjx-container[jax="SVG"] {
+  overflow-x: auto;
+
+  &[display="true"] {
+    margin-top: 0.7em !important;
+    margin-bottom: 0.7em !important;
+    padding-top: 0.3em;
+    padding-bottom: 0.3em;
+  }
+
+  > svg {
+    display: unset;
+    max-width: unset;
+    height: unset;
+  }
+}
+
+/********** TikZ SVG Styling **********/
+script[type="text/tikz"] {
+  display: block;
+}
+
+div > div[class="page"] > svg {
+  color-scheme: light dark;
+
+  html[data-theme="light"] & {
+    stroke: currentColor;
+    fill: currentColor;
+  }
+
+  html:not([data-theme="light"]) & {
+    stroke: white;
+    fill: white;
+    filter: invert(1) hue-rotate(180deg);
+  }
+}
+
+/********** Mimic Bootstrap Class Utilities **********/
+.visually-hidden {
+  display: none !important;
+}
+
+.visibility-hidden {
+  visibility: hidden !important;
+}
+
+.visible {
+  display: block !important;
+}
+
+.text-center {
+  text-align: center !important;
+}
+
+.d-block {
+  display: block !important;
+}
+
+.d-flex {
+  display: flex !important;
+}
+
+.flex-row {
+  flex-direction: row !important;
+}
+
+.flex-column {
+  flex-direction: column !important;
+}
+
+.justify-content-center {
+  justify-content: center !important;
+}
+
+.justify-content-between {
+  justify-content: space-between !important;
+}
+
+.justify-content-around {
+  justify-content: space-around !important;
+}
+
+.justify-content-evenly {
+  justify-content: space-evenly !important;
+}
+
+.align-items-center {
+  align-items: center !important;
+}
+
+.align-items-start {
+  align-items: flex-start !important;
+}
+
+.flex-wrap {
+  flex-wrap: wrap !important;
+
+  .flex-fill {
+    flex: 1 1 auto;
+    margin-top: unset;
+  }
+
+  .flex-fill.flex-code {
+    min-width: 0;
+  }
+}
+
+.flex-grow-1 {
+  flex-grow: 1 !important;
+}
+
+/* Overflow utilities */
+.overflow-auto {
+  overflow: auto !important;
+}
+
+.overflow-y-auto {
+  overflow-y: auto !important;
+}
+
+.overflow-x-hidden {
+  overflow-x: hidden !important;
+}
+
+/* Padding and Margin Utilities */
+/* Exposes utility classes like .p-0, .p-1, .pt-2, .mb-3, ..., .m-6, .gap-6 */
+
+$spacings: (
+  p: padding,
+  pt: padding-top,
+  pb: padding-bottom,
+  ps: padding-left,
+  pe: padding-right,
+  m: margin,
+  mt: margin-top,
+  mb: margin-bottom,
+  ms: margin-left,
+  me: margin-right,
+  gap: gap,
+  gap-row: row-gap,
+  gap-col: column-gap,
+);
+
+$axis-spacings: (
+  px: (
+    padding-left,
+    padding-right,
+  ),
+  py: (
+    padding-top,
+    padding-bottom,
+  ),
+  mx: (
+    margin-left,
+    margin-right,
+  ),
+  my: (
+    margin-top,
+    margin-bottom,
+  ),
+);
+
+@each $class, $property in $spacings {
+  .#{$class}-0 {
+    #{$property}: 0 !important;
+  }
+
+  $scalar: 0.125;
+  $accumulated: 0;
+
+  @for $i from 1 through 6 {
+    $scalar: $scalar + ($i % 2) * $scalar;
+    $accumulated: $accumulated + $scalar;
+
+    .#{$class}-#{$i} {
+      #{$property}: #{$accumulated}rem !important;
+    }
+  }
+}
+
+/* Axis-specific spacing utilities (-x and -y) */
+@each $class, $properties in $axis-spacings {
+  .#{$class}-0 {
+    @each $property in $properties {
+      #{$property}: 0 !important;
+    }
+  }
+
+  $scalar: 0.125;
+  $accumulated: 0;
+
+  @for $i from 1 through 6 {
+    $scalar: $scalar + ($i % 2) * $scalar;
+    $accumulated: $accumulated + $scalar;
+
+    .#{$class}-#{$i} {
+      @each $property in $properties {
+        #{$property}: #{$accumulated}rem !important;
+      }
+    }
+  }
+}
+
+/************ Custom Styles ************/
+
+.highlight-green,
+.highlight-red {
+  padding: 5px;
+}
+
+.highlight-green {
+  background: #7de37d34;
+}
+
+.highlight-red {
+  background: #f7535b46;
+}
+
+.admin-only {
+  display: none;
+}
+
+.note-indicator {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background-color: $info-color;
+  margin-right: 6px;
+  vertical-align: middle;
+  opacity: 0.6;
+}
+
+div.note {
+  display: none;
+  border: 3px solid $warning-color;
+  border-left: 6px solid $warning-color;
+  padding: 12px;
+  border-radius: 4px;
+  margin: 10px 0;
+
+  &::before {
+    content: "Personal Note";
+    display: block;
+    font-weight: bold;
+    color: $info-color;
+    margin-bottom: 8px;
+    font-size: 0.95em;
+  }
+}
+
+/********** Toggle Checkbox Styles **********/
+#toggle-all-details-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;
+      }
+    }
+  }
+}