starlight-cannoli-plugins 1.0.16 → 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-T4UKGKU6.js

@@ -0,0 +1,457 @@
+// src/plugins/remark-latex-compile/index.ts
+import { resolve } from "path";
+
+// src/plugins/remark-latex-compile/compile.ts
+import { createHash } from "crypto";
+import { spawnSync } from "child_process";
+import {
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  mkdtempSync
+} from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+// src/plugins/remark-latex-compile/error-parser.ts
+function parseLatexError(latexOutput) {
+  const lines = latexOutput.split("\n");
+  const errors = [];
+  const seenMessages = /* @__PURE__ */ new Set();
+  let hasFatal = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    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);
+          }
+          break;
+        }
+      }
+      errors.push({
+        message,
+        line: lineNum,
+        context: context.slice(0, 3),
+        severity: "error"
+      });
+    }
+  }
+  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"
+        });
+      }
+    }
+  }
+  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 (errors.length === 0 && latexOutput.length > 0) {
+    for (const line of lines) {
+      if (line.includes("error") || line.includes("Error") || line.includes("Misplaced") || line.includes("Missing")) {
+        const msg = line.trim();
+        if (!seenMessages.has(msg)) {
+          seenMessages.add(msg);
+          errors.push({
+            message: msg,
+            context: [],
+            severity: "error"
+          });
+        }
+        break;
+      }
+    }
+  }
+  if (errors.length === 0) {
+    errors.push({
+      message: "Unknown LaTeX compilation error",
+      context: [],
+      severity: "error"
+    });
+  }
+  return { errors, hasFatal };
+}
+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}`;
+  }
+  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 formattedSource = formatLatexSourceWithLineNumbers(
+    latexSource,
+    parsed.errors
+  );
+  return `${formatted}
+LaTeX source:
+${formattedSource}
+`;
+}
+
+// src/plugins/remark-latex-compile/compile.ts
+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);
+}
+function buildLatexSource(latexCode) {
+  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=4pt]{standalone}",
+    preamble,
+    "\\begin{document}",
+    "\\Large",
+    content,
+    "\\end{document}"
+  ].join("\n");
+}
+function compileLatexToSvg(latexCode, svgOutputDir) {
+  const hash = hashLatexCode(latexCode);
+  const svgPath = join(svgOutputDir, `${hash}.svg`);
+  if (existsSync(svgPath)) {
+    return { hash, svgPath, wasCompiled: false };
+  }
+  mkdirSync(svgOutputDir, { recursive: true });
+  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");
+    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);
+    }
+    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] PDF to SVG conversion failed (hash: ${hash}).
+Error: ${errorOutput}`
+      );
+    }
+  } finally {
+    try {
+      rmSync(workDir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+  return { hash, svgPath, wasCompiled: true };
+}
+
+// src/plugins/remark-latex-compile/index.ts
+function traverseTree(node, svgOutputDir, filePath, depth = 0) {
+  if (!node) return;
+  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(String(child.value), svgOutputDir);
+          children[i] = {
+            type: "paragraph",
+            children: [
+              {
+                type: "image",
+                url: `/static/tex-svgs/${result.hash}.svg`,
+                alt: "LaTeX diagram",
+                data: {
+                  hProperties: {
+                    className: ["tex-compiled"]
+                  }
+                }
+              }
+            ]
+          };
+        } catch (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, filePath, depth + 1);
+      }
+    }
+  }
+}
+function remarkLatexCompile(options) {
+  const svgOutputDir = resolve(options.svgOutputDir);
+  return (tree, file) => {
+    const fileObj = file;
+    const filePath = String(fileObj?.path || fileObj?.filename || "unknown");
+    traverseTree(tree, svgOutputDir, filePath, 0);
+  };
+}
+
+// src/plugins/remark-latex-compile/astro-integration.ts
+import { readdir, readFile, writeFile } from "fs/promises";
+import { resolve as resolve2, join as join2, extname } from "path";
+import { createHash as createHash2 } from "crypto";
+function hashLatexCode2(code) {
+  const normalized = code.split("\n").map((line) => line.trim()).join("\n").trim();
+  return createHash2("md5").update(normalized).digest("hex").slice(0, 16);
+}
+function createAstroLatexIntegration(options) {
+  const svgOutputDir = resolve2(options.svgOutputDir);
+  const contentDir = options?.contentDir ? resolve2(options.contentDir) : resolve2("src/content/docs");
+  return {
+    name: "astro-latex-compile",
+    hooks: {
+      "astro:build:start": async () => {
+        console.log(
+          "[astro-latex-compile] Build start, scanning for tex/latex compile blocks"
+        );
+        await scanAndCompileLatex(contentDir, svgOutputDir);
+      },
+      "astro:build:done": async ({ dir }) => {
+        console.log(
+          "[astro-latex-compile] Build done, updating HTML references"
+        );
+        try {
+          await updateHtmlReferences(dir.pathname, contentDir, svgOutputDir);
+        } catch (err) {
+          console.error(
+            "[astro-latex-compile] Error updating HTML references:",
+            err
+          );
+        }
+      }
+    }
+  };
+}
+async function scanAndCompileLatex(dir, svgOutputDir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join2(dir, entry.name);
+    if (entry.isDirectory()) {
+      await scanAndCompileLatex(fullPath, svgOutputDir);
+    } else if (entry.isFile()) {
+      const ext = extname(entry.name);
+      if (ext === ".md" || ext === ".mdx") {
+        await processMarkdownFile(fullPath, svgOutputDir);
+      }
+    }
+  }
+}
+function getLineNumber(content, position) {
+  return content.substring(0, position).split("\n").length;
+}
+async function processMarkdownFile(filePath, svgOutputDir) {
+  const content = await readFile(filePath, "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 lineNumber = getLineNumber(content, match.index || 0);
+    try {
+      const result = compileLatexToSvg(latexCode, svgOutputDir);
+      const status = result.wasCompiled ? "compiled" : "used cached";
+      console.log(
+        `[astro-latex-compile] ${filePath}:${lineNumber}: ${status} ${result.hash}.svg`
+      );
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      error.message = `${filePath}:${lineNumber}
+${error.message}`;
+      throw error;
+    }
+  }
+}
+async function updateHtmlReferences(buildDir, contentDir, svgOutputDir) {
+  const latexHashes = [];
+  const entries = await readdir(contentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join2(contentDir, entry.name);
+    if (entry.isDirectory()) {
+      await scanMarkdownForHashes(fullPath, latexHashes);
+    }
+  }
+  await updateHtmlDirWithHashes(buildDir, latexHashes, svgOutputDir);
+}
+async function scanMarkdownForHashes(dir, hashes) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join2(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 = hashLatexCode2(latexCode);
+        hashes.push(hash);
+      }
+    }
+  }
+}
+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, svgOutputDir);
+    } else if (entry.isFile() && entry.name.endsWith(".html")) {
+      let content = await readFile(fullPath, "utf-8");
+      let modified = false;
+      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}`);
+      }
+    }
+  }
+}
+
+// src/plugins/remark-latex-compile/starlight-plugin.ts
+function starlightLatexCompile(options) {
+  return {
+    name: "starlight-latex-compile",
+    hooks: {
+      "config:setup": (hook) => {
+        hook.addIntegration({
+          name: "latex-compile-remark-integration",
+          hooks: {
+            "astro:config:setup": ({ updateConfig, config }) => {
+              const existingPlugins = (Array.isArray(config.markdown?.remarkPlugins) ? config.markdown.remarkPlugins : []).filter((p) => p !== void 0 && p !== null);
+              updateConfig({
+                markdown: {
+                  remarkPlugins: [...existingPlugins, [remarkLatexCompile, options]]
+                }
+              });
+            }
+          }
+        });
+        hook.addIntegration(
+          createAstroLatexIntegration({
+            svgOutputDir: options.svgOutputDir
+          })
+        );
+      }
+    }
+  };
+}
+var starlight_plugin_default = starlightLatexCompile;
+
+export {
+  compileLatexToSvg,
+  starlightLatexCompile,
+  starlight_plugin_default,
+  remarkLatexCompile
+};

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-B9CyKYB4.d.ts

@@ -0,0 +1,41 @@
+import { HookParameters } from '@astrojs/starlight/types';
+
+interface CompilationResult {
+    hash: string;
+    svgPath: string;
+    wasCompiled: boolean;
+}
+/**
+ * Compile LaTeX code to SVG.
+ *
+ * @param latexCode - The LaTeX code to compile (e.g., TikZ, pgfplots, etc.)
+ * @param svgOutputDir - The directory where SVG files should be written
+ * @returns Result object with hash, svgPath, and whether compilation occurred
+ * @throws Error if compilation fails
+ */
+declare function compileLatexToSvg(latexCode: string, svgOutputDir: string): CompilationResult;
+
+/**
+ * Starlight plugin wrapper for remark-latex-compile.
+ *
+ * This plugin hooks into Starlight's config:setup to inject the remark-latex-compile
+ * plugin and the build-time Astro integration for scanning markdown files.
+ */
+
+type StarlightLatexCompileOptions = RemarkLatexCompileOptions;
+declare function starlightLatexCompile(options: StarlightLatexCompileOptions): {
+    name: string;
+    hooks: {
+        "config:setup": (hook: HookParameters<"config:setup">) => void;
+    };
+};
+
+interface RemarkLatexCompileOptions {
+    /**
+     * Directory where SVG files should be written.
+     */
+    svgOutputDir: string;
+}
+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,6 +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-B9CyKYB4.js';
 import '@astrojs/starlight/types';
 import 'hast';
 import 'vfile';

package/dist/index.js

@@ -4,6 +4,10 @@ import {
 import {
   rehypeValidateLinks
 } from "./chunk-HRUZQZ5L.js";
+import {
+  remarkLatexCompile,
+  starlightLatexCompile
+} from "./chunk-T4UKGKU6.js";
 
 // src/plugins/astro-normalize-paths.ts
 import { readFileSync, writeFileSync, existsSync } from "fs";
@@ -74,5 +78,7 @@ function normalizeAssetPath(path, htmlFile, siteRootPath) {
 export {
   astroNormalizePaths,
   rehypeValidateLinks,
-  starlightIndexOnlySidebar
+  remarkLatexCompile,
+  starlightIndexOnlySidebar,
+  starlightLatexCompile
 };

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

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1,10 @@
+import {
+  compileLatexToSvg,
+  remarkLatexCompile,
+  starlightLatexCompile
+} from "../chunk-T4UKGKU6.js";
+export {
+  compileLatexToSvg,
+  remarkLatexCompile as default,
+  starlightLatexCompile
+};

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

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

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

@@ -0,0 +1,8 @@
+import {
+  starlightLatexCompile,
+  starlight_plugin_default
+} 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.0.16",
+  "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",
@@ -23,6 +26,14 @@
       "import": "./dist/plugins/astro-normalize-paths.js",
       "types": "./dist/plugins/astro-normalize-paths.d.ts"
     },
+    "./remark-latex-compile": {
+      "import": "./dist/plugins/remark-latex-compile.js",
+      "types": "./dist/plugins/remark-latex-compile.d.ts"
+    },
+    "./starlight-latex-compile": {
+      "import": "./dist/plugins/starlight-latex-compile.js",
+      "types": "./dist/plugins/starlight-latex-compile.d.ts"
+    },
     "./styles": "./dist/styles/",
     "./styles/*": "./dist/styles/*"
   },
@@ -55,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",