starlight-cannoli-plugins 1.1.0 → 1.2.0

package/README.md

@@ -9,6 +9,7 @@ A collection of powerful plugins for [Astro Starlight](https://starlight.astro.b
 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:**
+
 - 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
@@ -38,7 +39,7 @@ export default defineConfig({
       plugins: [
         starlightIndexOnlySidebar({
           directories: ["guides", "api", "tutorials"],
-          maxDepthNesting: 2,           // optional
+          maxDepthNesting: 2, // optional
           dirnameDeterminesLabels: false, // optional
         }),
       ],
@@ -47,11 +48,123 @@ export default defineConfig({
 });
 ```
 
+### Starlight LaTeX Compile
+
+Automatically compiles fenced `tex compile` and `latex compile` code blocks to SVG diagrams during the build process. Uses `pdflatex` and `dvisvgm` for high-quality, cached SVG output.
+
+**Features:**
+
+- Compiles LaTeX/TikZ code blocks to SVG automatically
+- Caches compiled SVGs by content hash (no recompilation if unchanged)
+- Comprehensive error reporting with line numbers and formatted LaTeX source
+- Supports custom preamble via `%---` separator in code blocks
+- Works seamlessly with Starlight's content pipeline
+- Requires `svgOutputDir` configuration (no defaults)
+
+**System Requirements:**
+
+This plugin requires the following CLI tools to be installed and available on your system:
+
+- **`pdflatex`** — LaTeX compiler that produces PDF output
+- **`dvisvgm`** — Converts PDF to SVG format
+
+Verify installation by running:
+
+```bash
+pdflatex --version
+dvisvgm --version
+```
+
+**Usage:**
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import { starlightLatexCompile } from "cannoli-starlight-plugins";
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: "My Docs",
+      plugins: [
+        starlightLatexCompile({
+          svgOutputDir: "public/static/tex-svgs",
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+**Markdown Syntax:**
+
+````markdown
+```tex compile
+\begin{tikzpicture}
+  \node (A) at (0,0) {A};
+  \node (B) at (2,0) {B};
+  \draw (A) -- (B);
+\end{tikzpicture}
+```
+````
+
+**Custom Preamble:**
+
+Use `%---` to separate custom preamble from diagram content:
+
+````markdown
+```tex compile
+\usepackage{tikz-3dplot}
+
+%---
+
+\begin{tikzpicture}
+  % diagram code here
+\end{tikzpicture}
+```
+````
+
+### Remark LaTeX Compile
+
+The underlying remark plugin that powers `starlightLatexCompile`. Use this directly in Astro projects that don't use Starlight.
+
+**System Requirements:**
+
+Same as `starlightLatexCompile`:
+
+- **`pdflatex`** — LaTeX compiler that produces PDF output
+- **`dvisvgm`** — Converts PDF to SVG format
+
+**Usage:**
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import { remarkLatexCompile } from "cannoli-starlight-plugins/remark-latex-compile";
+
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [
+      [
+        remarkLatexCompile,
+        {
+          svgOutputDir: "public/static/tex-svgs",
+        },
+      ],
+    ],
+  },
+});
+```
+
+The plugin works identically to `starlightLatexCompile` but is configured directly in the Astro markdown pipeline.
+
 ### 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
@@ -68,9 +181,7 @@ import { rehypeValidateLinks } from "cannoli-starlight-plugins";
 
 export default defineConfig({
   markdown: {
-    rehypePlugins: [
-      rehypeValidateLinks,
-    ],
+    rehypePlugins: [rehypeValidateLinks],
   },
 });
 ```
@@ -100,7 +211,9 @@ Prepend a `?` to the link href to skip validation:
 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>
+<a href="csci-320-331-obrenic/grade-calculator" data-no-link-check>
+  Grade Calculator
+</a>
 ```
 
 **3. Global Skip Patterns** (Configuration-based)
@@ -112,17 +225,53 @@ Use the `skipPatterns` option to exclude links matching glob patterns:
 export default defineConfig({
   markdown: {
     rehypePlugins: [
-      [rehypeValidateLinks, {
-        skipPatterns: [
-          '/csci-320-331-obrenic/grade-calculator',  // exact match
-          '**/draft-*',                               // glob pattern
-        ]
-      }],
+      [
+        rehypeValidateLinks,
+        {
+          skipPatterns: [
+            "/csci-320-331-obrenic/grade-calculator", // exact match
+            "**/draft-*", // glob pattern
+          ],
+        },
+      ],
     ],
   },
 });
 ```
 
+## CLI Utilities
+
+### cannoli-latex-cleanup
+
+A cleanup utility for the LaTeX compile plugin. Scans your markdown source files for all `tex compile` code blocks, hashes them, and identifies orphaned SVG files in the output directory that are no longer referenced by any code block.
+
+**Usage:**
+
+Check for orphaned SVGs without deleting:
+
+```bash
+npx cannoli-latex-cleanup --svg-dir public/static/tex-svgs --check
+```
+
+Delete orphaned SVGs:
+
+```bash
+npx cannoli-latex-cleanup --svg-dir public/static/tex-svgs --delete
+```
+
+With custom docs directory (defaults to `src/content/docs`):
+
+```bash
+npx cannoli-latex-cleanup --svg-dir public/static/tex-svgs --docs-dir ./src/content/docs --delete
+```
+
+**Options:**
+
+- `--svg-dir` (required): Path to the SVG output directory configured in `starlightLatexCompile`
+- `--docs-dir` (optional, default: `src/content/docs`): Path to markdown source directory
+- `--check`: List orphaned SVGs without deleting
+- `--delete`: Delete orphaned SVGs
+
 ## Installation
 
 ```bash

package/dist/{chunk-IRJEKSXQ.js → chunk-T4UKGKU6.js}

@@ -3,13 +3,13 @@ import { resolve } from "path";
 
 // src/plugins/remark-latex-compile/compile.ts
 import { createHash } from "crypto";
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 import {
   existsSync,
   mkdirSync,
-  copyFileSync,
   writeFileSync,
-  rmSync
+  rmSync,
+  mkdtempSync
 } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -17,116 +17,151 @@ import { tmpdir } from "os";
 // src/plugins/remark-latex-compile/error-parser.ts
 function parseLatexError(latexOutput) {
   const lines = latexOutput.split("\n");
-  const errorLines = [];
-  let mainError = "";
-  let errorLineNum;
+  const errors = [];
+  const seenMessages = /* @__PURE__ */ new Set();
+  let hasFatal = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    if (line.includes("Undefined control sequence")) {
-      mainError = "Undefined control sequence";
-      errorLines.push(line);
-      for (let j = Math.max(0, i - 3); j <= Math.min(i + 3, lines.length - 1); j++) {
-        if (lines[j].startsWith("l.")) {
-          const match = lines[j].match(/^l\.(\d+)\s*(.*)/);
-          if (match) {
-            errorLineNum = parseInt(match[1], 10);
-            const sourceLine = match[2].trim();
-            if (sourceLine) {
-              mainError = `Undefined control sequence: ${sourceLine}`;
-            }
+    if (line.startsWith("!")) {
+      const message = line.substring(1).trim();
+      if (seenMessages.has(message)) continue;
+      seenMessages.add(message);
+      const context = [];
+      let lineNum;
+      for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+        const contextLine = lines[j];
+        if (contextLine.trim()) {
+          context.push(contextLine);
+        }
+        if (contextLine.startsWith("l.")) {
+          const lineMatch = contextLine.match(/^l\.(\d+)/);
+          if (lineMatch) {
+            lineNum = parseInt(lineMatch[1], 10);
           }
-          errorLines.push(lines[j]);
           break;
         }
       }
-      break;
+      errors.push({
+        message,
+        line: lineNum,
+        context: context.slice(0, 3),
+        severity: "error"
+      });
     }
   }
-  if (!mainError) {
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (line.startsWith("!")) {
-        mainError = line.substring(1).trim();
-        errorLines.push(line);
-        for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
-          const contextLine = lines[j];
-          if (contextLine.trim()) {
-            errorLines.push(contextLine);
-          }
-          if (contextLine.startsWith("l.")) {
-            break;
-          }
-        }
-        for (let j = i; j < Math.min(i + 10, lines.length); j++) {
-          const lineMatch = lines[j].match(/^l\.(\d+)/);
-          if (lineMatch) {
-            errorLineNum = parseInt(lineMatch[1], 10);
-            break;
-          }
-        }
-        break;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes("Overfull") || line.includes("Underfull")) {
+      const msg = line.trim();
+      if (!seenMessages.has(msg)) {
+        seenMessages.add(msg);
+        errors.push({
+          message: msg,
+          context: [],
+          severity: "warning"
+        });
       }
     }
   }
-  if (!mainError) {
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (line.toLowerCase().includes("emergency stop") || line.toLowerCase().includes("fatal error")) {
-        for (let j = Math.max(0, i - 5); j < i; j++) {
-          if (lines[j].startsWith("!")) {
-            mainError = lines[j].substring(1).trim();
-            errorLines.push(lines[j]);
-            break;
-          }
-        }
-        if (!mainError) {
-          mainError = line.trim();
-        }
-        break;
-      }
+  for (const line of lines) {
+    if (line.toLowerCase().includes("emergency stop") || line.toLowerCase().includes("fatal error") || line.toLowerCase().includes("not found")) {
+      hasFatal = true;
+      break;
     }
   }
-  if (!mainError && latexOutput.length > 0) {
+  if (errors.length === 0 && latexOutput.length > 0) {
     for (const line of lines) {
       if (line.includes("error") || line.includes("Error") || line.includes("Misplaced") || line.includes("Missing")) {
-        mainError = line.trim();
-        errorLines.push(mainError);
+        const msg = line.trim();
+        if (!seenMessages.has(msg)) {
+          seenMessages.add(msg);
+          errors.push({
+            message: msg,
+            context: [],
+            severity: "error"
+          });
+        }
         break;
       }
     }
   }
-  const message = mainError || "Unknown LaTeX compilation error";
-  return {
-    message,
-    line: errorLineNum,
-    context: errorLines.slice(0, 6)
-  };
+  if (errors.length === 0) {
+    errors.push({
+      message: "Unknown LaTeX compilation error",
+      context: [],
+      severity: "error"
+    });
+  }
+  return { errors, hasFatal };
 }
-function formatLatexError(error) {
-  let output = `LaTeX Error: ${error.message}`;
-  if (error.line) {
-    output += ` (line ${error.line})`;
+function formatLatexError(parsed) {
+  const RED = "\x1B[31m";
+  const YELLOW = "\x1B[33m";
+  const RESET = "\x1B[0m";
+  const errorCount = parsed.errors.filter((e) => e.severity === "error").length;
+  const warningCount = parsed.errors.filter(
+    (e) => e.severity === "warning"
+  ).length;
+  let output = `${RED}[remark-latex-compile] LaTeX compilation failed${RESET}
+`;
+  output += `${RED}${errorCount} error${errorCount !== 1 ? "s" : ""}${RESET}`;
+  if (warningCount > 0) {
+    output += `, ${YELLOW}${warningCount} warning${warningCount !== 1 ? "s" : ""}${RESET}`;
   }
-  if (error.context.length > 0) {
-    output += "\n\nContext:";
-    for (const contextLine of error.context) {
-      output += `
-  ${contextLine}`;
+  output += "\n\n";
+  const errorsByType = parsed.errors.reduce(
+    (acc, e) => {
+      if (!acc[e.severity]) acc[e.severity] = [];
+      acc[e.severity].push(e);
+      return acc;
+    },
+    {}
+  );
+  for (const err of errorsByType["error"] || []) {
+    output += `${RED}Error${RESET}`;
+    if (err.line) output += ` (line ${err.line})`;
+    output += `: ${err.message}
+`;
+    if (err.context.length > 0) {
+      output += `  Context: ${err.context[0]}
+`;
     }
   }
+  for (const warn of errorsByType["warning"] || []) {
+    output += `${YELLOW}Warning${RESET}: ${warn.message}
+`;
+  }
   return output;
 }
+function formatLatexSourceWithLineNumbers(latexSource, errors) {
+  const RED = "\x1B[31m";
+  const RESET = "\x1B[0m";
+  const lines = latexSource.split("\n");
+  const maxLineNum = lines.length;
+  const lineNumWidth = String(maxLineNum).length;
+  const errorLineNumbers = new Set(errors.map((e) => e.line).filter(Boolean));
+  const formattedLines = lines.map((line, index) => {
+    const lineNum = index + 1;
+    const lineNumStr = String(lineNum);
+    const padding = lineNumStr.length < lineNumWidth ? " " : "";
+    if (errorLineNumbers.has(lineNum)) {
+      return `${padding}${RED}[${lineNumStr}]:${RESET} ${line}`;
+    }
+    return `${padding}[${lineNumStr}]: ${line}`;
+  }).join("\n");
+  return formattedLines;
+}
 function createCompilationErrorMessage(latexSource, rawError) {
   const parsed = parseLatexError(rawError);
   const formatted = formatLatexError(parsed);
-  const RED = "\x1B[31m";
-  const RESET = "\x1B[0m";
-  return `${RED}[remark-latex-compile] LaTeX compilation failed${RESET}
-
-${formatted}
-
+  const formattedSource = formatLatexSourceWithLineNumbers(
+    latexSource,
+    parsed.errors
+  );
+  return `${formatted}
 LaTeX source:
-${latexSource}`;
+${formattedSource}
+`;
 }
 
 // src/plugins/remark-latex-compile/compile.ts
@@ -135,21 +170,20 @@ function hashLatexCode(code) {
   return createHash("md5").update(normalized).digest("hex").slice(0, 16);
 }
 function buildLatexSource(latexCode) {
-  const packageRegex = /\\usepackage\{[^}]+\}|\\usetikzlibrary\{[^}]+\}/g;
-  const packages = latexCode.match(packageRegex) || [];
-  const codeWithoutPackages = latexCode.replace(packageRegex, "").trim();
+  const separatorRegex = /%[ \t]*---/;
+  const parts = latexCode.split(separatorRegex);
+  let preamble = "";
+  let content = latexCode.trim();
+  if (parts.length === 2) {
+    preamble = parts[0].trim();
+    content = parts[1].trim();
+  }
   return [
-    "\\documentclass[border=0.5in]{standalone}",
-    ...packages,
-    "\\usepackage{xcolor}",
-    "\\pagecolor{white}",
+    "\\documentclass[border=4pt]{standalone}",
+    preamble,
     "\\begin{document}",
     "\\Large",
-    "\\fboxsep=2pt\\relax",
-    "\\fboxrule=0.5pt\\relax",
-    "\\fbox{",
-    codeWithoutPackages,
-    "}",
+    content,
     "\\end{document}"
   ].join("\n");
 }
@@ -160,43 +194,40 @@ function compileLatexToSvg(latexCode, svgOutputDir) {
     return { hash, svgPath, wasCompiled: false };
   }
   mkdirSync(svgOutputDir, { recursive: true });
-  const workDir = join(tmpdir(), `tikz-compile-${hash}`);
-  mkdirSync(workDir, { recursive: true });
-  const texFile = join(workDir, `${hash}.tex`);
-  const dviFile = join(workDir, `${hash}.dvi`);
-  const svgTempFile = join(workDir, `${hash}.svg`);
+  const workDir = mkdtempSync(join(tmpdir(), "latex-compile-"));
+  const texFile = join(workDir, "diagram.tex");
+  const pdfFile = join(workDir, "diagram.pdf");
   const latexSource = buildLatexSource(latexCode);
   try {
     writeFileSync(texFile, latexSource, "utf-8");
-    try {
-      execSync(
-        `latex -interaction=nonstopmode -output-directory "${workDir}" "${texFile}"`,
-        { stdio: "pipe", cwd: workDir, encoding: "utf-8" }
-      );
-    } catch (latexErr) {
-      const errorOutput = latexErr.stdout || latexErr.stderr || latexErr.message || "";
+    const latexResult = spawnSync("pdflatex", [
+      "-interaction=nonstopmode",
+      "-output-directory",
+      workDir,
+      texFile
+    ]);
+    if (latexResult.status !== 0) {
+      const errorOutput = latexResult.stderr?.toString() || latexResult.stdout?.toString() || "";
       const userMessage = createCompilationErrorMessage(
         latexSource,
         errorOutput
       );
       throw new Error(userMessage);
     }
-    try {
-      execSync(`dvisvgm --bbox=min "${dviFile}" -o "${svgTempFile}"`, {
-        stdio: "pipe",
-        cwd: workDir,
-        encoding: "utf-8"
-      });
-    } catch (dvisvgmErr) {
+    const dvisvgmResult = spawnSync("dvisvgm", [
+      "--pdf",
+      "--bbox=dvi",
+      pdfFile,
+      "-o",
+      svgPath
+    ]);
+    if (dvisvgmResult.status !== 0) {
+      const errorOutput = dvisvgmResult.stderr?.toString() || dvisvgmResult.stdout?.toString() || "";
       throw new Error(
-        `[remark-latex-compile] DVI to SVG conversion failed (hash: ${hash}).
-Error: ${dvisvgmErr.message}
-Stderr: ${dvisvgmErr.stderr ?? ""}Stdout: ${dvisvgmErr.stdout ?? ""}`
+        `[remark-latex-compile] PDF to SVG conversion failed (hash: ${hash}).
+Error: ${errorOutput}`
       );
     }
-    copyFileSync(svgTempFile, svgPath);
-  } catch (err) {
-    throw err;
   } finally {
     try {
       rmSync(workDir, { recursive: true, force: true });
@@ -207,37 +238,53 @@ Stderr: ${dvisvgmErr.stderr ?? ""}Stdout: ${dvisvgmErr.stdout ?? ""}`
 }
 
 // src/plugins/remark-latex-compile/index.ts
-function traverseTree(node, svgOutputDir, depth = 0) {
+function traverseTree(node, svgOutputDir, filePath, depth = 0) {
   if (!node) return;
-  if (Array.isArray(node.children)) {
-    for (let i = 0; i < node.children.length; i++) {
-      const child = node.children[i];
-      if (child.type === "code" && (child.lang === "tex" || child.lang === "latex") && child.meta?.includes("compile")) {
+  const children = node.children;
+  if (Array.isArray(children)) {
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      if (child.type === "code" && (child.lang === "tex" || child.lang === "latex") && String(child.meta || "").includes("compile")) {
         try {
-          const result = compileLatexToSvg(child.value, svgOutputDir);
-          node.children[i] = {
+          const result = compileLatexToSvg(String(child.value), svgOutputDir);
+          children[i] = {
             type: "paragraph",
             children: [
               {
                 type: "image",
                 url: `/static/tex-svgs/${result.hash}.svg`,
-                alt: "LaTeX diagram"
+                alt: "LaTeX diagram",
+                data: {
+                  hProperties: {
+                    className: ["tex-compiled"]
+                  }
+                }
               }
             ]
           };
         } catch (err) {
-          console.error(`[remarkLatexCompile] Failed to compile LaTeX code block:`, err);
+          if (process.env.NODE_ENV !== "production") {
+            const position = child.position;
+            const lineNumber = position?.start?.line || "?";
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            const match = errorMsg.match(/\n\n([\s\S]+)/);
+            const details = match ? match[1] : errorMsg;
+            console.error(`${filePath}:${lineNumber}
+${details}`);
+          }
         }
       } else {
-        traverseTree(child, svgOutputDir, depth + 1);
+        traverseTree(child, svgOutputDir, filePath, depth + 1);
       }
     }
   }
 }
 function remarkLatexCompile(options) {
-  const svgOutputDir = options?.svgOutputDir ? resolve(options.svgOutputDir) : resolve("public/static/tex-svgs");
-  return (tree) => {
-    traverseTree(tree, svgOutputDir, 0);
+  const svgOutputDir = resolve(options.svgOutputDir);
+  return (tree, file) => {
+    const fileObj = file;
+    const filePath = String(fileObj?.path || fileObj?.filename || "unknown");
+    traverseTree(tree, svgOutputDir, filePath, 0);
   };
 }
 
@@ -250,7 +297,7 @@ function hashLatexCode2(code) {
   return createHash2("md5").update(normalized).digest("hex").slice(0, 16);
 }
 function createAstroLatexIntegration(options) {
-  const svgOutputDir = options?.svgOutputDir ? resolve2(options.svgOutputDir) : resolve2("public/static/tex-svgs");
+  const svgOutputDir = resolve2(options.svgOutputDir);
   const contentDir = options?.contentDir ? resolve2(options.contentDir) : resolve2("src/content/docs");
   return {
     name: "astro-latex-compile",
@@ -259,14 +306,7 @@ function createAstroLatexIntegration(options) {
         console.log(
           "[astro-latex-compile] Build start, scanning for tex/latex compile blocks"
         );
-        try {
-          await scanAndCompileLatex(contentDir, svgOutputDir);
-        } catch (err) {
-          console.error(
-            "[astro-latex-compile] Error during LaTeX compilation:",
-            err
-          );
-        }
+        await scanAndCompileLatex(contentDir, svgOutputDir);
       },
       "astro:build:done": async ({ dir }) => {
         console.log(
@@ -315,10 +355,10 @@ async function processMarkdownFile(filePath, svgOutputDir) {
         `[astro-latex-compile] ${filePath}:${lineNumber}: ${status} ${result.hash}.svg`
       );
     } catch (err) {
-      console.error(
-        `[astro-latex-compile] Failed to compile LaTeX in ${filePath}:${lineNumber}:`,
-        err
-      );
+      const error = err instanceof Error ? err : new Error(String(err));
+      error.message = `${filePath}:${lineNumber}
+${error.message}`;
+      throw error;
     }
   }
 }
@@ -331,7 +371,7 @@ async function updateHtmlReferences(buildDir, contentDir, svgOutputDir) {
       await scanMarkdownForHashes(fullPath, latexHashes);
     }
   }
-  await updateHtmlDirWithHashes(buildDir, latexHashes);
+  await updateHtmlDirWithHashes(buildDir, latexHashes, svgOutputDir);
 }
 async function scanMarkdownForHashes(dir, hashes) {
   const entries = await readdir(dir, { withFileTypes: true });
@@ -351,26 +391,26 @@ async function scanMarkdownForHashes(dir, hashes) {
     }
   }
 }
-async function updateHtmlDirWithHashes(dir, hashes) {
+async function updateHtmlDirWithHashes(dir, hashes, svgOutputDir) {
   let hashIndex = 0;
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     const fullPath = join2(dir, entry.name);
     if (entry.isDirectory()) {
-      await updateHtmlDirWithHashes(fullPath, hashes);
+      await updateHtmlDirWithHashes(fullPath, hashes, svgOutputDir);
     } else if (entry.isFile() && entry.name.endsWith(".html")) {
       let content = await readFile(fullPath, "utf-8");
       let modified = false;
-      content = content.replace(
-        /src="\/static\/tex-svgs\/[a-f0-9]+\.svg"/g,
-        () => {
-          if (hashIndex < hashes.length) {
-            modified = true;
-            return `src="/static/tex-svgs/${hashes[hashIndex++]}.svg"`;
-          }
-          return arguments[0];
+      const pathSegments = svgOutputDir.split("/").slice(-2).join("/");
+      const htmlPath = `/${pathSegments}`;
+      const svgRegex = new RegExp(`src="${htmlPath}/[a-f0-9]+\\.svg"`, "g");
+      content = content.replace(svgRegex, (match) => {
+        if (hashIndex < hashes.length) {
+          modified = true;
+          return `src="${htmlPath}/${hashes[hashIndex++]}.svg"`;
         }
-      );
+        return match;
+      });
       if (modified) {
         await writeFile(fullPath, content, "utf-8");
         console.log(`[astro-latex-compile] Updated ${fullPath}`);
@@ -392,7 +432,7 @@ function starlightLatexCompile(options) {
               const existingPlugins = (Array.isArray(config.markdown?.remarkPlugins) ? config.markdown.remarkPlugins : []).filter((p) => p !== void 0 && p !== null);
               updateConfig({
                 markdown: {
-                  remarkPlugins: [...existingPlugins, [remarkLatexCompile, options ?? {}]]
+                  remarkPlugins: [...existingPlugins, [remarkLatexCompile, options]]
                 }
               });
             }
@@ -400,7 +440,7 @@ function starlightLatexCompile(options) {
         });
         hook.addIntegration(
           createAstroLatexIntegration({
-            svgOutputDir: options?.svgOutputDir
+            svgOutputDir: options.svgOutputDir
           })
         );
       }

package/dist/cli/cannoli-latex-cleanup.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/cannoli-latex-cleanup.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+// scripts/cli/cannoli-latex-cleanup.ts
+import { readdir, readFile, unlink } from "fs/promises";
+import { resolve, join } from "path";
+import { createHash } from "crypto";
+var args = process.argv.slice(2);
+var svgDir = null;
+var docsDir = "src/content/docs";
+var checkMode = false;
+var deleteMode = false;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--svg-dir" && i + 1 < args.length) {
+    svgDir = args[++i];
+  } else if (args[i] === "--docs-dir" && i + 1 < args.length) {
+    docsDir = args[++i];
+  } else if (args[i] === "--check") {
+    checkMode = true;
+  } else if (args[i] === "--delete") {
+    deleteMode = true;
+  }
+}
+if (!svgDir) {
+  console.error("Error: --svg-dir is required");
+  process.exit(1);
+}
+if (!checkMode && !deleteMode) {
+  console.error("Error: either --check or --delete must be specified");
+  process.exit(1);
+}
+var svgDirPath = resolve(svgDir);
+var docsDirPath = resolve(docsDir);
+function hashLatexCode(code) {
+  const normalized = code.split("\n").map((line) => line.trim()).join("\n").trim();
+  return createHash("md5").update(normalized).digest("hex").slice(0, 16);
+}
+async function scanMarkdownForHashes(dir, hashes) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await scanMarkdownForHashes(fullPath, hashes);
+      } else if (entry.isFile() && (entry.name.endsWith(".md") || entry.name.endsWith(".mdx"))) {
+        const content = await readFile(fullPath, "utf-8");
+        const latexBlockRegex = /```(?:tex|latex)\s+compile\n([\s\S]*?)\n```/g;
+        const matches = content.matchAll(latexBlockRegex);
+        for (const match of matches) {
+          const latexCode = match[1];
+          const hash = hashLatexCode(latexCode);
+          hashes.add(hash);
+        }
+      }
+    }
+  } catch (err) {
+    console.error(`Error scanning directory ${dir}:`, err);
+    throw err;
+  }
+}
+async function findOrphanedSvgs(svgPath, usedHashes) {
+  const orphaned = [];
+  try {
+    const entries = await readdir(svgPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".svg")) {
+        const hash = entry.name.replace(".svg", "");
+        if (!usedHashes.has(hash)) {
+          orphaned.push(join(svgPath, entry.name));
+        }
+      }
+    }
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      console.warn(`SVG directory does not exist: ${svgPath}`);
+      return [];
+    }
+    throw err;
+  }
+  return orphaned;
+}
+async function main() {
+  try {
+    console.log(`Scanning markdown files in ${docsDirPath}...`);
+    const usedHashes = /* @__PURE__ */ new Set();
+    await scanMarkdownForHashes(docsDirPath, usedHashes);
+    console.log(`Found ${usedHashes.size} unique tex compile blocks
+`);
+    console.log(`Scanning SVG directory ${svgDirPath}...`);
+    const orphanedSvgs = await findOrphanedSvgs(svgDirPath, usedHashes);
+    if (orphanedSvgs.length === 0) {
+      console.log("No orphaned SVGs found \u2713");
+      process.exit(0);
+    }
+    console.log(`
+Found ${orphanedSvgs.length} orphaned SVG(s):`);
+    orphanedSvgs.forEach((svg) => {
+      const filename = svg.split("/").pop();
+      console.log(`  - ${filename}`);
+    });
+    if (checkMode) {
+      console.log("\n(Use --delete to remove these files)");
+      process.exit(0);
+    }
+    if (deleteMode) {
+      console.log("\nDeleting orphaned SVGs...");
+      let deleted = 0;
+      for (const svg of orphanedSvgs) {
+        try {
+          await unlink(svg);
+          deleted++;
+          console.log(`  \u2713 Deleted ${svg.split("/").pop()}`);
+        } catch (err) {
+          console.error(`  \u2717 Failed to delete ${svg}:`, err);
+        }
+      }
+      console.log(`
+Deleted ${deleted}/${orphanedSvgs.length} files`);
+      process.exit(0);
+    }
+  } catch (err) {
+    console.error("Error:", err);
+    process.exit(1);
+  }
+}
+main();

package/dist/{index-DapkTQmZ.d.ts → index-B9CyKYB4.d.ts}

@@ -23,7 +23,7 @@ declare function compileLatexToSvg(latexCode: string, svgOutputDir: string): Com
  */
 
 type StarlightLatexCompileOptions = RemarkLatexCompileOptions;
-declare function starlightLatexCompile(options?: StarlightLatexCompileOptions): {
+declare function starlightLatexCompile(options: StarlightLatexCompileOptions): {
     name: string;
     hooks: {
         "config:setup": (hook: HookParameters<"config:setup">) => void;
@@ -33,10 +33,9 @@ declare function starlightLatexCompile(options?: StarlightLatexCompileOptions):
 interface RemarkLatexCompileOptions {
     /**
      * Directory where SVG files should be written.
-     * @default "public/static/tex-svgs"
      */
-    svgOutputDir?: string;
+    svgOutputDir: string;
 }
-declare function remarkLatexCompile(options?: RemarkLatexCompileOptions): (tree: any) => void;
+declare function remarkLatexCompile(options: RemarkLatexCompileOptions): (tree: Record<string, unknown>, file: unknown) => void;
 
 export { type RemarkLatexCompileOptions as R, type StarlightLatexCompileOptions as S, compileLatexToSvg as c, remarkLatexCompile as r, starlightLatexCompile as s };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { starlightIndexOnlySidebar } from './plugins/starlight-index-only-sidebar.js';
 export { default as rehypeValidateLinks } from './plugins/rehype-validate-links.js';
 import { AstroIntegration } from 'astro';
-export { r as remarkLatexCompile, s as starlightLatexCompile } from './index-DapkTQmZ.js';
+export { r as remarkLatexCompile, s as starlightLatexCompile } from './index-B9CyKYB4.js';
 import '@astrojs/starlight/types';
 import 'hast';
 import 'vfile';

package/dist/index.js

@@ -7,7 +7,7 @@ import {
 import {
   remarkLatexCompile,
   starlightLatexCompile
-} from "./chunk-IRJEKSXQ.js";
+} from "./chunk-T4UKGKU6.js";
 
 // src/plugins/astro-normalize-paths.ts
 import { readFileSync, writeFileSync, existsSync } from "fs";

package/dist/plugins/remark-latex-compile.d.ts

@@ -1,2 +1,2 @@
-export { R as RemarkLatexCompileOptions, c as compileLatexToSvg, r as default, s as starlightLatexCompile } from '../index-DapkTQmZ.js';
+export { R as RemarkLatexCompileOptions, c as compileLatexToSvg, r as default, s as starlightLatexCompile } from '../index-B9CyKYB4.js';
 import '@astrojs/starlight/types';

package/dist/plugins/remark-latex-compile.js

@@ -2,7 +2,7 @@ import {
   compileLatexToSvg,
   remarkLatexCompile,
   starlightLatexCompile
-} from "../chunk-IRJEKSXQ.js";
+} from "../chunk-T4UKGKU6.js";
 export {
   compileLatexToSvg,
   remarkLatexCompile as default,

package/dist/plugins/starlight-latex-compile.d.ts

@@ -1,2 +1,2 @@
 import '@astrojs/starlight/types';
-export { S as StarlightLatexCompileOptions, s as default, s as starlightLatexCompile } from '../index-DapkTQmZ.js';
+export { S as StarlightLatexCompileOptions, s as default, s as starlightLatexCompile } from '../index-B9CyKYB4.js';

package/dist/plugins/starlight-latex-compile.js

@@ -1,7 +1,7 @@
 import {
   starlightLatexCompile,
   starlight_plugin_default
-} from "../chunk-IRJEKSXQ.js";
+} from "../chunk-T4UKGKU6.js";
 export {
   starlight_plugin_default as default,
   starlightLatexCompile

package/dist/styles/_starlight.scss

@@ -179,3 +179,7 @@ img.note-svg {
     filter: invert(1) hue-rotate(180deg);
   }
 }
+
+.tex-compiled {
+  background-color: white;
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "starlight-cannoli-plugins",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Starlight plugins for automatic sidebar generation and link validation",
   "license": "ISC",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "cannoli-latex-cleanup": "./dist/cli/cannoli-latex-cleanup.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -63,7 +66,7 @@
     "clean:empty-dirs": "find src/content/docs -type d -empty -delete"
   },
   "dependencies": {
-    "eslint-cannoli-plugins": "^1.0.12",
+    "eslint-cannoli-plugins": "^1.0.13",
     "glob": "^13.0.6",
     "minimatch": "^10.2.4",
     "unist-util-visit": "^5.0.0",