starlight-cannoli-plugins 2.10.5 → 2.12.0

package/README.md

@@ -144,6 +144,7 @@ dvisvgm --version
 - `svgOutputDir` (required): Directory where compiled SVG files are written. Must be inside `public/` so Astro serves them as static assets.
 - `removeOrphanedSvgs` (optional, default: `false`): When `true`, SVG files that are no longer referenced by any `tex compile` block are deleted automatically. In dev mode, stale SVGs are removed immediately when a block is edited. On build, any remaining orphans are swept at the end.
 - `texInputDirs` (optional): Directories added to the TeX input search path (`TEXINPUTS`), allowing `\input{}` and `\include{}` to resolve files from your project. Use a trailing `/` to search only that directory, or `//` to search it recursively. Multiple directories are supported.
+- `tempOutputDir` (optional): When set, a JPEG copy of each compiled diagram is written to this directory, mirroring the folder structure of `src/content/docs/`. Only blocks that carry a `blockid=<n>` meta tag produce a JPEG — blocks without it are ignored. The filename format is `<originating-file>--<blockid>--<hash>.jpg` (e.g. `tex-test.md--5--abc123.jpg`). JPEGs are deleted automatically when their block is removed, its `blockid` changes, or its content changes. SVG output is unaffected — the JPEG is complementary and intended for local inspection.
 
 ```ts
 astroLatexCompile({

package/dist/{chunk-Q33KZ2RB.js → chunk-G2PJENXJ.js}

@@ -1,6 +1,7 @@
 // src/plugins/astro-latex-compile/index.ts
+import { existsSync as existsSync2 } from "fs";
 import { rm } from "fs/promises";
-import { join as join2, resolve } from "path";
+import { join as join2, resolve as resolve2 } from "path";
 import { visit, SKIP } from "unist-util-visit";
 import { MetaOptions } from "@expressive-code/core";
 
@@ -13,8 +14,9 @@ import {
   rmSync,
   mkdtempSync
 } from "fs";
-import { join } from "path";
+import { basename, dirname, join, resolve } from "path";
 import { tmpdir } from "os";
+import sharp from "sharp";
 
 // src/plugins/astro-latex-compile/error-parser.ts
 function parseLatexError(latexOutput) {
@@ -167,7 +169,7 @@ ${formattedSource}
 // src/plugins/utils/process-utils.ts
 import { spawn } from "child_process";
 function execProcess(command, args, options) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     let stdout = "";
     let stderr = "";
     const proc = spawn(command, args, { env: options?.env });
@@ -181,12 +183,78 @@ function execProcess(command, args, options) {
       reject(err);
     });
     proc.on("close", (code) => {
-      resolve2({ status: code ?? 1, stdout, stderr });
+      resolve3({ status: code ?? 1, stdout, stderr });
     });
   });
 }
 
 // src/plugins/astro-latex-compile/utils.ts
+var CONTENT_ROOT = "src/content/docs/";
+function computeJpgPath(tempOutputDir, filePath, blockId, hash) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const idx = normalized.indexOf(CONTENT_ROOT);
+  const relativePath = idx !== -1 ? normalized.slice(idx + CONTENT_ROOT.length) : basename(normalized);
+  const dir = dirname(relativePath);
+  const filename = basename(relativePath);
+  const jpgFilename = `${filename}--${blockId}--${hash}.jpg`;
+  const base = resolve(tempOutputDir);
+  return dir === "." ? join(base, jpgFilename) : join(base, dir, jpgFilename);
+}
+async function writeJpgFromSvg(svgPath, jpgPath) {
+  mkdirSync(dirname(jpgPath), { recursive: true });
+  await sharp(svgPath).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
+}
+function stripAnsi(text) {
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+function escapeXml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function wrapText(text, maxChars) {
+  const lines = [];
+  for (const raw of text.split("\n")) {
+    if (raw.length <= maxChars) {
+      lines.push(raw);
+    } else {
+      let remaining = raw;
+      while (remaining.length > maxChars) {
+        lines.push(remaining.slice(0, maxChars));
+        remaining = remaining.slice(maxChars);
+      }
+      if (remaining) lines.push(remaining);
+    }
+  }
+  return lines;
+}
+async function writeJpgError(jpgPath, header, errorText) {
+  const MAX_LINES = 40;
+  const clean = stripAnsi(errorText);
+  const sourceIdx = clean.indexOf("LaTeX source:");
+  const summary = (sourceIdx !== -1 ? clean.slice(0, sourceIdx) : clean).trimEnd();
+  let lines = wrapText(summary, 90);
+  if (lines.length > MAX_LINES) {
+    lines = lines.slice(0, MAX_LINES);
+    lines.push("...");
+  }
+  const fontSize = 13;
+  const lineHeight = 18;
+  const padding = 20;
+  const headerHeight = 55;
+  const width = 800;
+  const height = padding * 2 + headerHeight + lines.length * lineHeight;
+  const textLines = lines.map(
+    (line, i) => `<text x="${padding}" y="${padding + headerHeight + i * lineHeight}" font-family="monospace" font-size="${fontSize}" fill="#333333">${escapeXml(line)}</text>`
+  ).join("\n  ");
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+  <rect width="${width}" height="${height}" fill="white"/>
+  <rect x="0" y="0" width="${width}" height="4" fill="#cc0000"/>
+  <text x="${padding}" y="${padding + 20}" font-family="monospace" font-size="16" font-weight="bold" fill="#cc0000">LaTeX Compilation Error</text>
+  <text x="${padding}" y="${padding + 40}" font-family="monospace" font-size="12" fill="#666666">${escapeXml(header)}</text>
+  ${textLines}
+</svg>`;
+  mkdirSync(dirname(jpgPath), { recursive: true });
+  await sharp(Buffer.from(svg)).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
+}
 function hashLatexCode(code) {
   const normalized = code.split("\n").map((line) => line.trim()).filter((line) => !line.startsWith("%")).filter(Boolean).join("\n").trim();
   return createHash("md5").update(normalized).digest("hex").slice(0, 16);
@@ -285,7 +353,7 @@ Error: ${errorOutput}`
 
 // src/plugins/astro-latex-compile/index.ts
 function remarkLatexCompile(options) {
-  const svgOutputDir = resolve(options.svgOutputDir);
+  const svgOutputDir = resolve2(options.svgOutputDir);
   return async function transformer(tree, file) {
     const nodes = [];
     visit(tree, "code", (node, index, parent) => {
@@ -298,7 +366,10 @@ function remarkLatexCompile(options) {
     const filePath = file.path || "unknown";
     const results = await Promise.all(
       nodes.map(async ({ node, index, parent }) => {
-        const lineNumber = node.position?.start.line ?? "?";
+        const lineNumberStr = node.position?.start.line ?? "?";
+        const blockId = new MetaOptions(node.meta ?? "").getInteger("blockid");
+        const contentHash = hashLatexCode(node.value);
+        const canWriteJpg = !!options.tempOutputDir && blockId !== void 0;
         try {
           const result = await compileLatexToSvg(
             node.value,
@@ -307,20 +378,49 @@ function remarkLatexCompile(options) {
           );
           if (result.wasCompiled) {
             console.log(
-              `[remark-latex-compile] ${filePath}:${lineNumber}: compiled ${result.hash}.svg`
+              `[remark-latex-compile] ${filePath}:${lineNumberStr}: compiled ${result.hash}.svg`
             );
           }
           options._referencedHashes?.add(result.hash);
-          return { index, parent, result, error: null, hash: result.hash };
+          const jpgPath = canWriteJpg ? computeJpgPath(options.tempOutputDir, filePath, blockId, contentHash) : null;
+          if (jpgPath && !existsSync2(jpgPath)) {
+            await writeJpgFromSvg(result.svgPath, jpgPath);
+            console.log(
+              `[remark-latex-compile] ${filePath}:${lineNumberStr}: wrote ${jpgPath}`
+            );
+          }
+          return {
+            index,
+            parent,
+            result,
+            error: null,
+            hash: result.hash,
+            jpgPath
+          };
         } catch (err) {
           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(
-            `[remark-latex-compile] ${filePath}:${lineNumber}
+            `[remark-latex-compile] ${filePath}:${lineNumberStr}
 ${details}`
           );
-          return { index, parent, result: null, error: err, hash: null };
+          const jpgPath = canWriteJpg ? computeJpgPath(options.tempOutputDir, filePath, blockId, `${contentHash}--error`) : null;
+          if (jpgPath && !existsSync2(jpgPath)) {
+            await writeJpgError(
+              jpgPath,
+              `${filePath}:${lineNumberStr}`,
+              errorMsg
+            );
+          }
+          return {
+            index,
+            parent,
+            result: null,
+            error: err,
+            hash: null,
+            jpgPath
+          };
         }
       })
     );
@@ -342,6 +442,20 @@ ${details}`
       );
       options._fileHashMap.set(filePath, newHashes);
     }
+    if (options.tempOutputDir && options._fileJpgPathMap) {
+      const newJpgPaths = new Set(
+        results.map((r) => r.jpgPath).filter(Boolean)
+      );
+      const oldJpgPaths = options._fileJpgPathMap.get(filePath) ?? /* @__PURE__ */ new Set();
+      const staleJpgPaths = [...oldJpgPaths].filter((p) => !newJpgPaths.has(p));
+      for (const stalePath of staleJpgPaths) {
+        console.warn(
+          `[remark-latex-compile] Removing orphaned jpg: ${stalePath}`
+        );
+      }
+      await Promise.all(staleJpgPaths.map((p) => rm(p, { force: true })));
+      options._fileJpgPathMap.set(filePath, newJpgPaths);
+    }
     for (let i = results.length - 1; i >= 0; i--) {
       const { index, parent, result } = results[i];
       const { node } = nodes[i];

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 } from "./chunk-3UMY7T6G.js";
 import {
   remarkLatexCompile
-} from "./chunk-Q33KZ2RB.js";
+} from "./chunk-G2PJENXJ.js";
 import {
   astroNormalizePaths
 } from "./chunk-TLOFSB33.js";
@@ -243,6 +243,7 @@ async function clearContentLayerCache(config) {
 function astroLatexCompile(options) {
   const referencedHashes = /* @__PURE__ */ new Set();
   const fileHashMap = /* @__PURE__ */ new Map();
+  const fileJpgPathMap = /* @__PURE__ */ new Map();
   return {
     name: "astro-latex-compile",
     hooks: {
@@ -255,7 +256,8 @@ function astroLatexCompile(options) {
         const remarkOptions = {
           ...options,
           _fileHashMap: options.removeOrphanedSvgs ? fileHashMap : void 0,
-          _referencedHashes: command === "build" && options.removeOrphanedSvgs ? referencedHashes : void 0
+          _referencedHashes: command === "build" && options.removeOrphanedSvgs ? referencedHashes : void 0,
+          _fileJpgPathMap: options.tempOutputDir ? fileJpgPathMap : void 0
         };
         updateConfig({
           markdown: {

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

@@ -29,6 +29,15 @@ interface RemarkLatexCompileOptions {
      * search (e.g. "src/latex/" or "src/latex//").
      */
     texInputDirs?: string[];
+    /**
+     * When set, a JPEG copy of each compiled diagram is written here, mirroring
+     * the folder structure of `src/content/docs/`. Only blocks that carry a
+     * `blockid=<n>` meta tag produce a JPEG. Filename format:
+     * `<originating-file>--<blockid>--<hash>.jpg`.
+     * JPEGs are deleted automatically when their block is removed or its content
+     * changes. Intended for local inspection, not for publishing.
+     */
+    tempOutputDir?: string;
     /**
      * @internal Populated by the Astro integration to track which hashes were
      * referenced during a build, used for full orphan cleanup at build:done.
@@ -39,6 +48,11 @@ interface RemarkLatexCompileOptions {
      * previous remark run. Used to delete stale SVGs when a block changes.
      */
     _fileHashMap?: Map<string, Set<string>>;
+    /**
+     * @internal Maps each file path to the set of JPG paths it produced on the
+     * previous remark run. Used to delete stale JPGs when a block changes.
+     */
+    _fileJpgPathMap?: Map<string, Set<string>>;
 }
 declare function remarkLatexCompile(options: RemarkLatexCompileOptions): (tree: Root, file: VFile) => Promise<void>;
 

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

@@ -1,7 +1,7 @@
 import {
   compileLatexToSvg,
   remarkLatexCompile
-} from "../chunk-Q33KZ2RB.js";
+} from "../chunk-G2PJENXJ.js";
 import "../chunk-4VNS5WPM.js";
 export {
   compileLatexToSvg,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-cannoli-plugins",
   "type": "module",
-  "version": "2.10.5",
+  "version": "2.12.0",
   "description": "Starlight plugins for automatic sidebar generation and link validation",
   "license": "ISC",
   "main": "./dist/index.js",
@@ -74,6 +74,7 @@
     "glob": "^11.0.0",
     "jsdom": "^29.0.2",
     "minimatch": "^9.0.0",
+    "sharp": "^0.34.5",
     "unist-util-visit": "^5.0.0",
     "yaml": "^2.4.0"
   },
@@ -123,7 +124,6 @@
     "rehype-raw": "^7.0.0",
     "remark-math": "^6.0.0",
     "sass-embedded": "^1.97.3",
-    "sharp": "^0.34.2",
     "tsup": "^8.3.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",