starlight-cannoli-plugins 1.0.16 → 1.1.0

package/dist/chunk-IRJEKSXQ.js

@@ -0,0 +1,417 @@
+// src/plugins/remark-latex-compile/index.ts
+import { resolve } from "path";
+
+// src/plugins/remark-latex-compile/compile.ts
+import { createHash } from "crypto";
+import { execSync } from "child_process";
+import {
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  writeFileSync,
+  rmSync
+} 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 errorLines = [];
+  let mainError = "";
+  let errorLineNum;
+  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}`;
+            }
+          }
+          errorLines.push(lines[j]);
+          break;
+        }
+      }
+      break;
+    }
+  }
+  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;
+      }
+    }
+  }
+  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;
+      }
+    }
+  }
+  if (!mainError && 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);
+        break;
+      }
+    }
+  }
+  const message = mainError || "Unknown LaTeX compilation error";
+  return {
+    message,
+    line: errorLineNum,
+    context: errorLines.slice(0, 6)
+  };
+}
+function formatLatexError(error) {
+  let output = `LaTeX Error: ${error.message}`;
+  if (error.line) {
+    output += ` (line ${error.line})`;
+  }
+  if (error.context.length > 0) {
+    output += "\n\nContext:";
+    for (const contextLine of error.context) {
+      output += `
+  ${contextLine}`;
+    }
+  }
+  return output;
+}
+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}
+
+LaTeX source:
+${latexSource}`;
+}
+
+// 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 packageRegex = /\\usepackage\{[^}]+\}|\\usetikzlibrary\{[^}]+\}/g;
+  const packages = latexCode.match(packageRegex) || [];
+  const codeWithoutPackages = latexCode.replace(packageRegex, "").trim();
+  return [
+    "\\documentclass[border=0.5in]{standalone}",
+    ...packages,
+    "\\usepackage{xcolor}",
+    "\\pagecolor{white}",
+    "\\begin{document}",
+    "\\Large",
+    "\\fboxsep=2pt\\relax",
+    "\\fboxrule=0.5pt\\relax",
+    "\\fbox{",
+    codeWithoutPackages,
+    "}",
+    "\\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 = 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 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 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) {
+      throw new Error(
+        `[remark-latex-compile] DVI to SVG conversion failed (hash: ${hash}).
+Error: ${dvisvgmErr.message}
+Stderr: ${dvisvgmErr.stderr ?? ""}Stdout: ${dvisvgmErr.stdout ?? ""}`
+      );
+    }
+    copyFileSync(svgTempFile, svgPath);
+  } catch (err) {
+    throw err;
+  } 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, 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")) {
+        try {
+          const result = compileLatexToSvg(child.value, svgOutputDir);
+          node.children[i] = {
+            type: "paragraph",
+            children: [
+              {
+                type: "image",
+                url: `/static/tex-svgs/${result.hash}.svg`,
+                alt: "LaTeX diagram"
+              }
+            ]
+          };
+        } catch (err) {
+          console.error(`[remarkLatexCompile] Failed to compile LaTeX code block:`, err);
+        }
+      } else {
+        traverseTree(child, svgOutputDir, depth + 1);
+      }
+    }
+  }
+}
+function remarkLatexCompile(options) {
+  const svgOutputDir = options?.svgOutputDir ? resolve(options.svgOutputDir) : resolve("public/static/tex-svgs");
+  return (tree) => {
+    traverseTree(tree, svgOutputDir, 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 = options?.svgOutputDir ? resolve2(options.svgOutputDir) : resolve2("public/static/tex-svgs");
+  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"
+        );
+        try {
+          await scanAndCompileLatex(contentDir, svgOutputDir);
+        } catch (err) {
+          console.error(
+            "[astro-latex-compile] Error during LaTeX compilation:",
+            err
+          );
+        }
+      },
+      "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) {
+      console.error(
+        `[astro-latex-compile] Failed to compile LaTeX in ${filePath}:${lineNumber}:`,
+        err
+      );
+    }
+  }
+}
+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);
+}
+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) {
+  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);
+    } 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];
+        }
+      );
+      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/index-DapkTQmZ.d.ts

@@ -0,0 +1,42 @@
+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.
+     * @default "public/static/tex-svgs"
+     */
+    svgOutputDir?: string;
+}
+declare function remarkLatexCompile(options?: RemarkLatexCompileOptions): (tree: any) => 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-DapkTQmZ.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-IRJEKSXQ.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-DapkTQmZ.js';
+import '@astrojs/starlight/types';

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

@@ -0,0 +1,10 @@
+import {
+  compileLatexToSvg,
+  remarkLatexCompile,
+  starlightLatexCompile
+} from "../chunk-IRJEKSXQ.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-DapkTQmZ.js';

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-cannoli-plugins",
   "type": "module",
-  "version": "1.0.16",
+  "version": "1.1.0",
   "description": "Starlight plugins for automatic sidebar generation and link validation",
   "license": "ISC",
   "main": "./dist/index.js",
@@ -23,6 +23,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/*"
   },