starlight-cannoli-plugins 2.17.1 → 2.18.0

package/README.md

@@ -144,7 +144,7 @@ dvisvgm --version
 - `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.
 - `svgClassname` (optional): Default CSS class(es) applied to every compiled SVG `<img>` element. Individual blocks can override this with a `class` meta tag value. The `tex-compiled` class is always present and cannot be overridden.
 - `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. When any file in these directories changes, all cached SVGs are invalidated and recompiled.
-- `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.
+- `debug` (optional): When set, a JPEG copy of each compiled diagram is written to `debug.outputDir` as a flat file list (no mirrored folder structure). Only blocks that carry a `blockid=<n>` meta tag produce a JPEG — blocks without it are ignored. The filename format is `<originating-file>--<blockid>-<8-char-dir-checksum>.jpg` (e.g. `tex-test--5-a1b2c3d4.jpg`), where the checksum is an MD5 hash of the originating file's directory, namespacing files so that same-named files from different directories don't collide. JPEGs are deleted automatically when their block is removed, its `blockid` changes, or its content changes, and the entire `debug.outputDir` is cleared on dev server startup. Every JPEG (re)write is also appended to `debug.logFile`, which rotates automatically once it grows too large (rolling backups `<logFile>-1.log`, `<logFile>-2.log`, etc.). SVG output is unaffected — the JPEG/log output is complementary and intended for local inspection.
 
 ```ts
 astroLatexCompile({
@@ -364,11 +364,15 @@ export default defineConfig({
 
 - `preserveDirs` (required): Names of child directories inside `public/` to preserve during sync. These will not be deleted when re-syncing.
 - `ignorePatterns` (optional): Glob patterns for files to exclude from syncing. Patterns are matched against paths relative to `src/content/docs/`.
+- `exposePageSrcButton` (optional, default: `false`): Injects a client-side script on every page that adds a `⋮` dropdown next to the page's `<h1>` with "Copy Page", "Copy raw URL", and "View raw" actions for the page's raw markdown source.
+- `enableAskAiOption` (optional, default: `false`): Adds "Ask ChatGPT", "Ask Claude", and "Ask Gemini" entries to the same `⋮` dropdown, each opening the respective chat app in a new tab with a prompt pre-filled to read the page's raw markdown URL. Independent of `exposePageSrcButton` — enabling this on its own still injects the dropdown button, containing only the "Ask" entries.
 
 ```ts
 syncDocsToPublic({
   preserveDirs: ["static"],
   ignorePatterns: ["**/*.txt", "**/drafts/**"],
+  exposePageSrcButton: true,
+  enableAskAiOption: true,
 });
 ```
 

package/dist/{chunk-4ZJKEEDA.js → chunk-BM7LMGAH.js}

@@ -138,17 +138,18 @@ var DEFAULT_SRC_DIR = "src/content/docs";
 var DEFAULT_PUBLIC_DIR = "public";
 function validateOptions(options) {
   const mdProbePaths = ["test.md", "test.mdx", "foo/test.md", "foo/test.mdx"];
-  if (!options.exposePageSrcButton) return;
+  const needsRawMd = options.exposePageSrcButton || options.enableAskAiOption;
+  if (!needsRawMd) return;
   const offendingMdPatterns = (options.ignorePatterns ?? []).filter(
     (pattern) => mdProbePaths.some((probe) => minimatch(probe, pattern, { dot: true }))
   );
   const offendingMtPatternsStr = offendingMdPatterns.map((p) => `    - "${p}"`).join("\n");
   if (offendingMdPatterns.length > 0) {
     throw new Error(
-      `The 'exposePageSrcButton' option is enabled but the following 'ignorePatterns' values conflict with it: 
+      `The 'exposePageSrcButton'/'enableAskAiOption' option is enabled but the following 'ignorePatterns' values conflict with it: 
 ${offendingMtPatternsStr}
 
-Since these ignore patterns match md/mdx files, the page source button would break. Either disable 'exposePageSrcButton' or remove these patterns.`
+Since these ignore patterns match md/mdx files, the page action button would break. Either disable these options or remove these patterns.`
     );
   }
 }
@@ -256,7 +257,8 @@ function syncDocsToPublic(options) {
   const {
     preserveDirs: rawPreserveDirs,
     ignorePatterns = [],
-    exposePageSrcButton = false
+    exposePageSrcButton = false,
+    enableAskAiOption = false
   } = options;
   const preserveDirs = rawPreserveDirs.map((d) => d.replace(/\/+$/, ""));
   return {
@@ -264,7 +266,7 @@ function syncDocsToPublic(options) {
     hooks: {
       "astro:config:setup": ({ injectScript }) => {
         validateOptions(options);
-        if (exposePageSrcButton) {
+        if (exposePageSrcButton || enableAskAiOption) {
           injectScript(
             "page",
             `
@@ -288,8 +290,16 @@ function syncDocsToPublic(options) {
               import.meta.url
             );
           }
-          const scriptPath = fileURLToPath(pageScriptUrl);
-          injectScript("page", `import ${JSON.stringify(scriptPath)};`);
+          const scriptPath = JSON.stringify(fileURLToPath(pageScriptUrl));
+          const actionBarOptions = JSON.stringify({
+            exposePageSrcButton,
+            enableAskAiOption
+          });
+          injectScript(
+            "page",
+            `import { initPageActionBar } from ${scriptPath};
+initPageActionBar(${actionBarOptions});`
+          );
         }
       },
       "astro:build:start": async () => {

package/dist/{chunk-FDEHNCBK.js → chunk-GVS36MVT.js}

@@ -9,18 +9,67 @@ import { join as join2, relative as relative2, resolve as resolve2 } from "path"
 import { visit, SKIP } from "unist-util-visit";
 import { MetaOptions } from "@expressive-code/core";
 
+// src/plugins/utils/rotating-file-logger.ts
+import { existsSync, mkdirSync, renameSync, rmSync, statSync } from "fs";
+import { appendFile } from "fs/promises";
+import { dirname, extname } from "path";
+function rotatedPath(filePath, index) {
+  const ext = extname(filePath);
+  const base = filePath.slice(0, filePath.length - ext.length);
+  return `${base}-${index}${ext}`;
+}
+function formatTimestamp(date) {
+  const pad = (n, width = 2) => String(n).padStart(width, "0");
+  const datePart = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+  const timePart = `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())},${pad(date.getMilliseconds(), 3)}`;
+  return `${datePart} ${timePart}`;
+}
+function rotate(options) {
+  const { filePath, backupCount } = options;
+  const oldestPath = rotatedPath(filePath, backupCount);
+  if (existsSync(oldestPath)) {
+    rmSync(oldestPath);
+  }
+  for (let index = backupCount - 1; index >= 1; index--) {
+    const source = rotatedPath(filePath, index);
+    if (existsSync(source)) {
+      renameSync(source, rotatedPath(filePath, index + 1));
+    }
+  }
+  if (backupCount >= 1) {
+    renameSync(filePath, rotatedPath(filePath, 1));
+  } else {
+    rmSync(filePath);
+  }
+}
+var RotatingFileLogger = class {
+  options;
+  constructor(options) {
+    this.options = options;
+    mkdirSync(dirname(options.filePath), { recursive: true });
+  }
+  async write(message) {
+    const { filePath, maxSizeBytes, identifier } = this.options;
+    const line = `[${identifier}] ${formatTimestamp(/* @__PURE__ */ new Date())} ${message}${message.endsWith("\n") ? "" : "\n"}`;
+    if (existsSync(filePath) && statSync(filePath).size >= maxSizeBytes) {
+      rotate(this.options);
+    }
+    await appendFile(filePath, line);
+  }
+};
+
 // src/plugins/astro-latex-compile/utils.ts
 import { createHash } from "crypto";
 import {
-  existsSync,
-  mkdirSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
   readdirSync,
   readFileSync,
   writeFileSync,
-  rmSync,
+  rmSync as rmSync2,
   mkdtempSync
 } from "fs";
-import { basename, dirname, join, relative, resolve } from "path";
+import { basename, dirname as dirname2, extname as extname2, join, relative, resolve } from "path";
 import { tmpdir } from "os";
 import sharp from "sharp";
 
@@ -251,18 +300,18 @@ function html(literalValues, ...interpolatedValues) {
 
 // src/plugins/astro-latex-compile/utils.ts
 var CONTENT_ROOT = "src/content/docs/";
-function computeJpgPath(tempOutputDir, filePath, blockId) {
+function computeJpgPath(outputDir, filePath, blockId) {
   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}.jpg`;
-  const base = resolve(tempOutputDir);
-  return dir === "." ? join(base, jpgFilename) : join(base, dir, jpgFilename);
+  const dir = dirname2(relativePath);
+  const filename = basename(relativePath, extname2(relativePath));
+  const dirChecksum = createHash("md5").update(dir).digest("hex").slice(0, 8);
+  const jpgFilename = `${filename}--${blockId}-${dirChecksum}.jpg`;
+  return join(resolve(outputDir), jpgFilename);
 }
 async function writeJpgFromSvg(svgPath, jpgPath) {
-  mkdirSync(dirname(jpgPath), { recursive: true });
+  mkdirSync2(dirname2(jpgPath), { recursive: true });
   await sharp(svgPath, { density: 300 }).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
 }
 function stripAnsi(text) {
@@ -313,7 +362,7 @@ async function writeJpgError(jpgPath, header, errorText) {
   <text x="${padding}" y="${padding + 40}" font-family="monospace" font-size="12" fill="#666666">${escapeXml(header)}</text>
   ${textLines}
 </svg>`;
-  mkdirSync(dirname(jpgPath), { recursive: true });
+  mkdirSync2(dirname2(jpgPath), { recursive: true });
   await sharp(Buffer.from(svg)).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
 }
 function computeLineOffset(_latexCode) {
@@ -418,10 +467,10 @@ function buildLatexSource(latexCode) {
 async function compileLatexToSvg(latexCode, svgOutputDir, texInputDirs = [], inputsSalt = "") {
   const hash = hashLatexCode(latexCode, inputsSalt);
   const svgPath = join(svgOutputDir, `${hash}.svg`);
-  if (existsSync(svgPath)) {
+  if (existsSync2(svgPath)) {
     return { hash, svgPath, wasCompiled: false };
   }
-  mkdirSync(svgOutputDir, { recursive: true });
+  mkdirSync2(svgOutputDir, { recursive: true });
   const workDir = mkdtempSync(join(tmpdir(), "latex-compile-"));
   const texFile = join(workDir, "diagram.tex");
   const pdfFile = join(workDir, "diagram.pdf");
@@ -479,7 +528,7 @@ Error: ${errorOutput}`
     }
   } finally {
     try {
-      rmSync(workDir, { recursive: true, force: true });
+      rmSync2(workDir, { recursive: true, force: true });
     } catch {
     }
   }
@@ -487,6 +536,8 @@ Error: ${errorOutput}`
 }
 
 // src/plugins/astro-latex-compile/index.ts
+var DEBUG_LOG_MAX_SIZE_BYTES = 5 * 1024 * 1024;
+var DEBUG_LOG_BACKUP_COUNT = 3;
 function getFrontmatterOffset(absoluteFilePath) {
   try {
     const original = readFileSync2(absoluteFilePath, "utf-8");
@@ -499,6 +550,12 @@ function getFrontmatterOffset(absoluteFilePath) {
 }
 function latexCompileTransformer(options) {
   const svgOutputDir = resolve2(options.svgOutputDir);
+  const debugLogger = options.debug ? new RotatingFileLogger({
+    identifier: "astro-latex-compile",
+    filePath: options.debug.logFile,
+    maxSizeBytes: DEBUG_LOG_MAX_SIZE_BYTES,
+    backupCount: DEBUG_LOG_BACKUP_COUNT
+  }) : null;
   return async function transformer(tree, file) {
     const nodes = [];
     visit(tree, "code", (node, index, parent) => {
@@ -516,7 +573,7 @@ function latexCompileTransformer(options) {
       nodes.map(async ({ node, index, parent }) => {
         const lineNumberStr = node.position?.start.line !== void 0 ? String(node.position.start.line + frontmatterOffset) : "?";
         const blockId = new MetaOptions(node.meta ?? "").getInteger("blockid");
-        const jpgPath = options.tempOutputDir && blockId !== void 0 ? computeJpgPath(options.tempOutputDir, filePath, blockId) : null;
+        const jpgPath = options.debug && blockId !== void 0 ? computeJpgPath(options.debug.outputDir, filePath, blockId) : null;
         try {
           const result = await compileLatexToSvg(
             node.value,
@@ -532,8 +589,8 @@ function latexCompileTransformer(options) {
           options._referencedHashes?.add(result.hash);
           if (jpgPath) {
             await writeJpgFromSvg(result.svgPath, jpgPath);
-            console.log(
-              `[astro-latex-compile] ${relFilePath}:${lineNumberStr}: wrote ${jpgPath}`
+            await debugLogger?.write(
+              `${relFilePath}:${lineNumberStr}: wrote ${jpgPath}`
             );
           }
           return {
@@ -588,7 +645,7 @@ ${details}`
       );
       options._fileHashMap.set(filePath, newHashes);
     }
-    if (options.tempOutputDir && options._fileJpgPathMap) {
+    if (options.debug && options._fileJpgPathMap) {
       const newJpgPaths = new Set(
         results.map((r) => r.jpgPath).filter(Boolean)
       );

package/dist/index.js

@@ -9,14 +9,14 @@ import {
 } from "./chunk-3UMY7T6G.js";
 import {
   latexCompileTransformer
-} from "./chunk-FDEHNCBK.js";
+} from "./chunk-GVS36MVT.js";
 import {
   astroNormalizePaths
 } from "./chunk-TLOFSB33.js";
 import "./chunk-LJWSZSPB.js";
 import {
   syncDocsToPublic
-} from "./chunk-4ZJKEEDA.js";
+} from "./chunk-BM7LMGAH.js";
 import {
   parseFrontmatter
 } from "./chunk-EEPQVOZC.js";
@@ -311,12 +311,24 @@ function astroLatexCompile(options) {
         if (command === "build") {
           await clearContentLayerCache(config);
         }
+        if (command === "dev" && options.debug) {
+          const debugOutputDir = resolve2(options.debug.outputDir);
+          let entries;
+          try {
+            entries = await readdir(debugOutputDir);
+          } catch {
+            entries = [];
+          }
+          await Promise.all(
+            entries.filter((f) => f.endsWith(".jpg")).map((f) => rm(join3(debugOutputDir, f), { force: true }))
+          );
+        }
         const existingPlugins = Array.isArray(config.markdown?.remarkPlugins) ? config.markdown.remarkPlugins.filter(Boolean) : [];
         const pluginOptions = {
           ...options,
           _fileHashMap: options.removeOrphanedSvgs ? fileHashMap : void 0,
           _referencedHashes: command === "build" && options.removeOrphanedSvgs ? referencedHashes : void 0,
-          _fileJpgPathMap: options.tempOutputDir ? fileJpgPathMap : void 0
+          _fileJpgPathMap: options.debug ? fileJpgPathMap : void 0
         };
         updateConfig({
           markdown: {

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

@@ -36,14 +36,20 @@ interface LatexCompilePluginOptions {
      */
     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`.
+     * When set, a JPEG copy of each compiled diagram is written to a flat
+     * directory. Only blocks that carry a `blockid=<n>` meta tag produce a
+     * JPEG. Filename format: `<originating-file>-<8-char-dir-checksum>--<blockid>.jpg`,
+     * where the checksum namespaces files originating from different
+     * directories to avoid collisions between files with the same name.
      * JPEGs are deleted automatically when their block is removed or its content
      * changes. Intended for local inspection, not for publishing.
      */
-    tempOutputDir?: string;
+    debug?: {
+        /** Directory where debug JPEGs are written, as a flat file list. */
+        outputDir: string;
+        /** Path to a log file that records every JPEG (re)write. Rotates by size. */
+        logFile: string;
+    };
     /**
      * @internal Populated by the Astro integration to track which hashes were
      * referenced during a build, used for full orphan cleanup at build:done.

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

@@ -1,7 +1,7 @@
 import {
   compileLatexToSvg,
   latexCompileTransformer
-} from "../chunk-FDEHNCBK.js";
+} from "../chunk-GVS36MVT.js";
 import "../chunk-7D2KLZGE.js";
 import "../chunk-4VNS5WPM.js";
 export {

package/dist/plugins/astro-sync-docs-to-public/page-script.d.ts

@@ -1,2 +1,7 @@
+interface ActionBarOptions {
+    exposePageSrcButton: boolean;
+    enableAskAiOption: boolean;
+}
+declare function initPageActionBar(options: ActionBarOptions): void;
 
-export {  }
+export { initPageActionBar };

package/dist/plugins/astro-sync-docs-to-public/page-script.js

@@ -1,3 +1,5 @@
+import "../../chunk-4VNS5WPM.js";
+
 // src/plugins/astro-sync-docs-to-public/page-script.ts
 function showBanner(message, variant) {
   const banner = document.createElement("div");
@@ -28,7 +30,21 @@ async function getRawMdUrl() {
   }
   return new URL("index.md", base).toString();
 }
-function createActionBar() {
+var LLM_ASK_TARGETS = [
+  {
+    label: "Ask ChatGPT",
+    buildUrl: (prompt) => `https://chatgpt.com/?${new URLSearchParams({ q: prompt })}`
+  },
+  {
+    label: "Ask Claude",
+    buildUrl: (prompt) => `https://claude.ai/new?${new URLSearchParams({ q: prompt })}`
+  },
+  {
+    label: "Ask Gemini",
+    buildUrl: (prompt) => `https://gemini.google.com/app?${new URLSearchParams({ q: prompt })}`
+  }
+];
+function createActionBar(options) {
   const bar = document.createElement("div");
   bar.className = "page-src-action-bar";
   const menuBtn = document.createElement("button");
@@ -39,29 +55,48 @@ function createActionBar() {
   }
   const menu = document.createElement("div");
   menu.className = "page-src-action-bar__menu";
-  const menuItems = [
-    {
-      label: "Copy Page",
-      action: () => {
-        setLoading(true);
-        getRawMdUrl().then((url) => fetch(url)).then((resp) => resp.text()).then((text) => navigator.clipboard.writeText(text)).then(() => showBanner("Page source copied to clipboard!", "success")).catch(() => showBanner("Failed to copy page source.", "error")).finally(() => setLoading(false));
-      }
-    },
-    {
-      label: "Copy raw URL",
-      action: () => {
-        setLoading(true);
-        getRawMdUrl().then((url) => navigator.clipboard.writeText(url)).then(() => showBanner("Raw URL copied to clipboard!", "success")).catch(() => showBanner("Failed to copy raw URL.", "error")).finally(() => setLoading(false));
-      }
-    },
-    {
-      label: "View raw",
-      action: () => {
-        setLoading(true);
-        getRawMdUrl().then((url) => window.open(url, "_blank")).catch(() => showBanner("Failed to open raw source.", "error")).finally(() => setLoading(false));
+  const menuItems = [];
+  if (options.exposePageSrcButton) {
+    menuItems.push(
+      {
+        label: "Copy Page",
+        action: () => {
+          setLoading(true);
+          getRawMdUrl().then((url) => fetch(url)).then((resp) => resp.text()).then((text) => navigator.clipboard.writeText(text)).then(
+            () => showBanner("Page source copied to clipboard!", "success")
+          ).catch(() => showBanner("Failed to copy page source.", "error")).finally(() => setLoading(false));
+        }
+      },
+      {
+        label: "Copy raw URL",
+        action: () => {
+          setLoading(true);
+          getRawMdUrl().then((url) => navigator.clipboard.writeText(url)).then(() => showBanner("Raw URL copied to clipboard!", "success")).catch(() => showBanner("Failed to copy raw URL.", "error")).finally(() => setLoading(false));
+        }
+      },
+      {
+        label: "View raw",
+        action: () => {
+          setLoading(true);
+          getRawMdUrl().then((url) => window.open(url, "_blank")).catch(() => showBanner("Failed to open raw source.", "error")).finally(() => setLoading(false));
+        }
       }
+    );
+  }
+  if (options.enableAskAiOption) {
+    for (const { label, buildUrl } of LLM_ASK_TARGETS) {
+      menuItems.push({
+        label,
+        action: () => {
+          setLoading(true);
+          getRawMdUrl().then((url) => {
+            const prompt = `Read from ${url} so I can ask questions about it.`;
+            window.open(buildUrl(prompt), "_blank");
+          }).catch(() => showBanner(`Failed to open ${label}.`, "error")).finally(() => setLoading(false));
+        }
+      });
     }
-  ];
+  }
   for (const item of menuItems) {
     const btn = document.createElement("button");
     btn.className = "page-src-action-bar__menu-item";
@@ -93,13 +128,15 @@ function createActionBar() {
   bar.appendChild(menu);
   return bar;
 }
-function main() {
+function initPageActionBar(options) {
   const h1 = document.querySelector(".sl-container > h1");
   if (h1 === null) return;
   const wrapper = document.createElement("div");
   wrapper.className = "page-src-h1-wrapper";
   h1.replaceWith(wrapper);
   wrapper.appendChild(h1);
-  wrapper.appendChild(createActionBar());
+  wrapper.appendChild(createActionBar(options));
 }
-main();
+export {
+  initPageActionBar
+};

package/dist/plugins/astro-sync-docs-to-public.d.ts

@@ -17,6 +17,15 @@ interface SyncDocsToPublicOptions {
      * dev and build modes.
      */
     exposePageSrcButton?: boolean;
+    /**
+     * When true, adds "Ask ChatGPT", "Ask Claude", and "Ask Gemini" entries to
+     * the page action dropdown menu, each opening the respective chat app with
+     * a prompt pre-filled to read the current page's raw markdown URL.
+     *
+     * Independent of `exposePageSrcButton` — enabling this on its own still
+     * injects the dropdown button, containing only the "Ask" entries.
+     */
+    enableAskAiOption?: boolean;
 }
 declare function syncDocsToPublic(options: SyncDocsToPublicOptions): AstroIntegration;
 

package/dist/plugins/astro-sync-docs-to-public.js

@@ -1,6 +1,6 @@
 import {
   syncDocsToPublic
-} from "../chunk-4ZJKEEDA.js";
+} from "../chunk-BM7LMGAH.js";
 import "../chunk-EEPQVOZC.js";
 import "../chunk-7D2KLZGE.js";
 import "../chunk-4VNS5WPM.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-cannoli-plugins",
   "type": "module",
-  "version": "2.17.1",
+  "version": "2.18.0",
   "description": "Starlight plugins for automatic sidebar generation and link validation",
   "license": "ISC",
   "main": "./dist/index.js",