@kenjura/ursa 0.72.0 → 0.75.0

package/src/helper/breadcrumbs.js

@@ -0,0 +1,42 @@
+import { toTitleCase } from "./build/titleCase.js";
+
+/**
+ * Generate breadcrumb navigation HTML from a document's path.
+ *
+ * @param {string} dir  - Directory relative to source root, e.g. "settings/eberron/" or "/"
+ * @param {string} base - Filename without extension, e.g. "index" or "places"
+ * @param {object} [fileMeta] - Parsed frontmatter (used for current-page label override)
+ * @returns {string} Breadcrumb HTML string, or empty string if not applicable
+ */
+export function generateBreadcrumbs(dir, base, fileMeta) {
+  const segments = dir.split('/').filter(Boolean);
+  const isIndexFile = (base === 'index' || base === 'home');
+
+  // All path segments leading to the current page
+  const allSegments = isIndexFile ? segments : [...segments, base];
+
+  // No breadcrumbs for root-level pages (need at least 1 segment beyond root)
+  if (allSegments.length < 1) return '';
+
+  const parts = [`<a class="breadcrumb-link" href="/">Home</a>`];
+  let href = '/';
+
+  for (let i = 0; i < allSegments.length; i++) {
+    const seg = allSegments[i];
+    const isLast = i === allSegments.length - 1;
+
+    // Current page can use frontmatter title; others use title-cased folder name
+    const label = isLast && fileMeta?.title
+      ? fileMeta.title
+      : toTitleCase(seg);
+
+    if (isLast) {
+      parts.push(`<span class="breadcrumb-current" aria-current="page">${label}</span>`);
+    } else {
+      href += seg + '/';
+      parts.push(`<a class="breadcrumb-link" href="${href}">${label}</a>`);
+    }
+  }
+
+  return `<nav class="breadcrumbs" aria-label="Breadcrumbs">${parts.join('<span class="breadcrumb-sep" aria-hidden="true">/</span>')}</nav>\n`;
+}

package/src/helper/build/autoIndex.js

@@ -9,6 +9,35 @@ import { toTitleCase } from "./titleCase.js";
 import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
 import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
 import { getCustomMenuForFile } from "./menu.js";
+import { generateBreadcrumbs } from "../breadcrumbs.js";
+
+// Document extensions for checking if a folder has content
+const SOURCE_DOC_EXTENSIONS = ['.md', '.mdx', '.txt', '.yml', '.html'];
+const OUTPUT_DOC_EXTENSIONS = ['.html'];
+
+/**
+ * Recursively check if a directory contains any document files.
+ * @param {string} dir - Directory path to check
+ * @param {string[]} extensions - File extensions that count as documents
+ * @returns {Promise<boolean>} True if the directory (or any subdirectory) contains at least one document
+ */
+async function directoryHasDocuments(dir, extensions) {
+  try {
+    const children = await readdir(dir, { withFileTypes: true });
+    for (const child of children) {
+      if (child.name.startsWith('.')) continue;
+      const fullPath = join(dir, child.name);
+      if (child.isDirectory()) {
+        if (child.name === 'img') continue;
+        if (await directoryHasDocuments(fullPath, extensions)) return true;
+      } else {
+        const ext = extname(child.name).toLowerCase();
+        if (extensions.includes(ext)) return true;
+      }
+    }
+  } catch (e) { /* ignore */ }
+  return false;
+}
 
 /**
  * Generate auto-index HTML content for a directory from the OUTPUT folder
@@ -50,6 +79,11 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
     
     for (const child of filteredChildren) {
       const isDir = child.isDirectory();
+      // Skip directories that contain no documents
+      if (isDir) {
+        const childDir = join(dir, child.name);
+        if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+      }
       const name = isDir ? child.name : child.name.replace('.html', '');
       // Use pathPrefix to ensure hrefs are correct relative to the document root
       const childPath = pathPrefix ? `${pathPrefix}/${child.name}` : child.name;
@@ -99,11 +133,11 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
         // Skip hidden files
         if (child.name.startsWith('.')) return false;
         // Skip index files (we're generating into the index)
-        if (child.name.match(/^index\.(md|txt|yml|html)$/i)) return false;
+        if (child.name.match(/^index\.(md|mdx|txt|yml|html)$/i)) return false;
         // Skip img folders (contain images, not content)
         if (child.isDirectory() && child.name === 'img') return false;
-        // Include directories and article files (md, txt, yml, html)
-        return child.isDirectory() || child.name.match(/\.(md|txt|yml|html)$/i);
+        // Include directories and article files (md, mdx, txt, yml, html)
+        return child.isDirectory() || child.name.match(/\.(md|mdx|txt|yml|html)$/i);
       })
       .sort((a, b) => {
         // Directories first, then files, alphabetically within each group
@@ -120,6 +154,11 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
     
     for (const child of filteredChildren) {
       const isDir = child.isDirectory();
+      // Skip directories that contain no documents
+      if (isDir) {
+        const childDir = join(sourceDir, child.name);
+        if (!await directoryHasDocuments(childDir, SOURCE_DOC_EXTENSIONS)) continue;
+      }
       // Get name without extension for display
       const ext = isDir ? '' : extname(child.name);
       const nameWithoutExt = isDir ? child.name : basename(child.name, ext);
@@ -262,23 +301,29 @@ export async function generateAutoIndices(output, directories, source, templates
         const children = await readdir(dir, { withFileTypes: true });
         
         // Filter to only include relevant files and folders
-        const items = children
-          .filter(child => {
-            // Skip hidden files and index alternates we just checked
-            if (child.name.startsWith('.')) return false;
-            if (child.name === 'index.html') return false;
-            // Include directories and html files
-            return child.isDirectory() || child.name.endsWith('.html');
-          })
-          .map(child => {
-            const isDir = child.isDirectory();
-            const name = isDir ? child.name : child.name.replace('.html', '');
-            // For directories, link to /folder/index.html; for files, use the filename directly
-            const href = isDir ? `${child.name}/index.html` : child.name;
-            const displayName = toTitleCase(name);
-            const icon = isDir ? '📁' : '📄';
-            return `<li>${icon} <a href="${href}">${displayName}</a></li>`;
-          });
+        const filteredItems = children.filter(child => {
+          // Skip hidden files and index alternates we just checked
+          if (child.name.startsWith('.')) return false;
+          if (child.name === 'index.html') return false;
+          // Include directories and html files
+          return child.isDirectory() || child.name.endsWith('.html');
+        });
+
+        // Build items, skipping directories with no documents
+        const items = [];
+        for (const child of filteredItems) {
+          const isDir = child.isDirectory();
+          if (isDir) {
+            const childDir = join(dir, child.name);
+            if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+          }
+          const name = isDir ? child.name : child.name.replace('.html', '');
+          // For directories, link to /folder/index.html; for files, use the filename directly
+          const href = isDir ? `${child.name}/index.html` : child.name;
+          const displayName = toTitleCase(name);
+          const icon = isDir ? '📁' : '📄';
+          items.push(`<li>${icon} <a href="${href}">${displayName}</a></li>`);
+        }
         
         if (items.length === 0) {
           // Empty folder, skip generating index
@@ -286,7 +331,13 @@ export async function generateAutoIndices(output, directories, source, templates
         }
         
         const folderDisplayName = dir === outputNorm ? 'Home' : toTitleCase(folderName);
-        const indexHtml = `<h1>${folderDisplayName}</h1>\n<ul class="auto-index">\n${items.join('\n')}\n</ul>`;
+
+        // Generate breadcrumbs for auto-index pages
+        const relDir = dir.replace(outputNorm, '').replace(/^\//, '');
+        const breadcrumbDir = relDir ? relDir + '/' : '/';
+        const breadcrumbHtml = generateBreadcrumbs(breadcrumbDir, 'index', null);
+
+        const indexHtml = `${breadcrumbHtml}<h1>${folderDisplayName}</h1>\n<ul class="auto-index">\n${items.join('\n')}\n</ul>`;
         
         const template = templates["default-template"];
         if (!template) {
@@ -357,13 +408,19 @@ export async function generateAutoIndices(output, directories, source, templates
           finalHtml = finalHtml.replace(key, value);
         }
         
-        // Add custom menu data attributes if applicable
+        // Add menu data attributes to body
         if (customMenuInfo) {
-          const menuPosition = customMenuInfo.menuPosition || 'side';
+          const menuPosition = customMenuInfo.menuPosition || 'top';
           finalHtml = finalHtml.replace(
             /<body([^>]*)>/,
             `<body$1 data-custom-menu="${customMenuInfo.menuJsonPath}" data-menu-position="${menuPosition}">`
           );
+        } else {
+          // No custom menu — default to top menu
+          finalHtml = finalHtml.replace(
+            /<body([^>]*)>/,
+            `<body$1 data-menu-position="top">`
+          );
         }
         
         // Add cache-busting timestamps to static file references

package/src/helper/build/menu.js

@@ -48,7 +48,7 @@ export function findAllCustomMenus(allSourceFilenames, source) {
           menuPath: menuInfo.path,
           menuDir: menuInfo.menuDir,
           menuData: parsedMenu.menuData,
-          menuPosition: parsedMenu.menuPosition || 'side',
+          menuPosition: parsedMenu.menuPosition || 'top',
           // The URL path for the menu JSON file
           menuJsonPath: '/public/custom-menu-' + getMenuId(menuInfo.menuDir, source) + '.json',
         });
@@ -60,7 +60,7 @@ export function findAllCustomMenus(allSourceFilenames, source) {
         let menuData;
         if (autoGenerate) {
           // Auto-generate menu and combine with manual content
-          const depth = parseInt(frontmatter['menu-depth'], 10) || 2;
+          const depth = parseInt(frontmatter['menu-depth'], 10) || 10;
           menuData = combineAutoAndManualMenu(body, menuInfo.menuDir, source, depth);
         } else {
           menuData = parseCustomMenu(body, menuInfo.menuDir, source);
@@ -70,7 +70,7 @@ export function findAllCustomMenus(allSourceFilenames, source) {
           menuPath: menuInfo.path,
           menuDir: menuInfo.menuDir,
           menuData,
-          menuPosition: frontmatter['menu-position'] || 'side',
+          menuPosition: frontmatter['menu-position'] || 'top',
           // The URL path for the menu JSON file
           menuJsonPath: '/public/custom-menu-' + getMenuId(menuInfo.menuDir, source) + '.json',
         });
@@ -112,7 +112,7 @@ export function getCustomMenuForFile(filePath, source, customMenus) {
       return {
         menuJsonPath: menuInfo.menuJsonPath,
         menuDir: relative(source, menuInfo.menuDir) || '',
-        menuPosition: menuInfo.menuPosition || 'side',
+        menuPosition: menuInfo.menuPosition || 'top',
       };
     }
     const parentDir = dirname(currentDir);

package/src/helper/customMenu.js

@@ -18,6 +18,64 @@ const INDEX_NAMES = ['index', 'home'];
 // Default icons
 const FOLDER_ICON = '📁';
 const DOCUMENT_ICON = '📄';
+const HOME_ICON = '🏠';
+
+/**
+ * Collapse single-document folders into direct links.
+ * If a folder's only children are index-like files (no sub-folders),
+ * collapse it to a direct link using the folder's label and the first child's href.
+ * @param {Array} items - Menu items
+ * @returns {Array} - Processed menu items
+ */
+function collapseSingleDocFolders(items) {
+  return items.map(item => {
+    if (!item.hasChildren || !item.children || item.children.length === 0) return item;
+    
+    // Recurse first so nested single-doc folders are collapsed bottom-up
+    item.children = collapseSingleDocFolders(item.children);
+    
+    // Check if all children are non-folder items (i.e., no child has children)
+    const hasSubfolders = item.children.some(c => c.hasChildren);
+    if (!hasSubfolders && item.children.length > 0) {
+      // All children are leaf files — if there's only one, collapse to a direct link
+      // For index-like content (single child), collapse the folder entirely
+      if (item.children.length === 1) {
+        const onlyChild = item.children[0];
+        return {
+          ...item,
+          hasChildren: false,
+          children: [],
+          href: onlyChild.href || item.href,
+        };
+      }
+    }
+    
+    return item;
+  });
+}
+
+/**
+ * Recursively check if a folder contains any document files.
+ * @param {string} dirPath - Directory to check
+ * @returns {boolean} True if the folder (or any subfolder) contains at least one document
+ */
+function folderHasDocuments(dirPath) {
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+      const fullPath = join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'img') continue;
+        if (folderHasDocuments(fullPath)) return true;
+      } else {
+        const ext = extname(entry.name);
+        if (SOURCE_EXTENSIONS.includes(ext)) return true;
+      }
+    }
+  } catch (e) { /* ignore */ }
+  return false;
+}
 
 /**
  * Extract frontmatter from menu file content
@@ -113,30 +171,18 @@ function getMenuLabelFromFile(filePath) {
  * Similar to the main automenu but for custom menu contexts
  * @param {string} folderPath - Absolute path to folder
  * @param {string} sourceRoot - Root source directory
- * @param {number} depth - How deep to recurse (default: 2)
+ * @param {number} depth - How deep to recurse (default: 10)
  * @param {boolean} isRoot - Whether this is the root level (adds Home item)
  * @returns {Array} - Menu items array
  */
-export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 2, isRoot = true) {
+export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 10, isRoot = true) {
   const items = [];
   
   if (depth <= 0 || !existsSync(folderPath)) {
     return items;
   }
   
-  // Home item to be added at the start (after sorting other items)
-  let homeItem = null;
-  if (isRoot) {
-    const relativePath = '/' + relative(sourceRoot, folderPath).replace(/\\/g, '/');
-    homeItem = {
-      label: 'Home',
-      path: 'home',
-      href: relativePath + '/index.html',
-      hasChildren: false,
-      icon: `<span class="menu-icon">${DOCUMENT_ICON}</span>`,
-      children: [],
-    };
-  }
+  // (Home item is built at the end for root level, after partitioning)
   
   try {
     const entries = readdirSync(folderPath, { withFileTypes: true });
@@ -155,6 +201,9 @@ export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 2, is
       const relativePath = '/' + relative(sourceRoot, fullPath).replace(/\\/g, '/');
       
       if (entry.isDirectory()) {
+        // Skip folders that contain no documents (recursively)
+        if (!folderHasDocuments(fullPath)) continue;
+
         // Check for index file to get label
         let label = null;
         for (const ext of SOURCE_EXTENSIONS) {
@@ -182,6 +231,8 @@ export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 2, is
         const baseName = basename(entry.name, ext);
         // Skip index files (they're represented by the folder)
         if (INDEX_NAMES.includes(baseName.toLowerCase())) continue;
+        // Skip foldername-matching files (e.g. Arcanist/Arcanist.md — represented by the folder)
+        if (baseName.toLowerCase() === basename(folderPath).toLowerCase()) continue;
         
         // Get label from frontmatter or filename
         const label = getMenuLabelFromFile(fullPath) || toDisplayName(baseName);
@@ -197,23 +248,39 @@ export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 2, is
       }
     }
     
-    // Sort: folders first, then alphabetically
+    // Sort: folders first (a-z), then files (a-z), case-insensitive
     items.sort((a, b) => {
       if (a.hasChildren && !b.hasChildren) return -1;
       if (!a.hasChildren && b.hasChildren) return 1;
-      return a.label.localeCompare(b.label);
+      return a.label.localeCompare(b.label, undefined, { sensitivity: 'base' });
     });
     
   } catch (e) {
     console.error(`Error reading folder ${folderPath}:`, e);
   }
   
-  // Add Home item at the very start (after sorting)
-  if (homeItem) {
-    items.unshift(homeItem);
+  // Post-process: collapse single-doc folders into direct links
+  const processedItems = collapseSingleDocFolders(items);
+  
+  if (isRoot) {
+    // Partition top-level items: files go under Home, folders stay at top level
+    const topLevelFolders = processedItems.filter(item => item.hasChildren);
+    const topLevelFiles = processedItems.filter(item => !item.hasChildren);
+    
+    const relativePath = '/' + relative(sourceRoot, folderPath).replace(/\\/g, '/');
+    const homeItem = {
+      label: 'Home',
+      path: 'home',
+      href: relativePath + '/index.html',
+      hasChildren: topLevelFiles.length > 0,
+      icon: `<span class="menu-icon">${HOME_ICON}</span>`,
+      children: topLevelFiles,
+    };
+    
+    return [homeItem, ...topLevelFolders];
   }
   
-  return items;
+  return processedItems;
 }
 
 /**
@@ -241,7 +308,7 @@ export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 2, is
  * @param {number} depth - How many levels deep to auto-generate
  * @returns {Array} - Combined menu data array
  */
-export function combineAutoAndManualMenu(manualContent, menuDir, sourceRoot, depth = 2) {
+export function combineAutoAndManualMenu(manualContent, menuDir, sourceRoot, depth = 10) {
   // Generate the auto menu
   const autoMenuItems = autoGenerateMenuFromFolder(menuDir, sourceRoot, depth, true);
   
@@ -422,15 +489,31 @@ export function parseCustomMenu(content, menuDir, sourceRoot) {
       // It's a relative path - resolve it relative to the menu directory
       absoluteSourcePath = resolve(menuDir, href);
       
-      // Check if the path already has a source extension (.md, .txt)
+      // Check if the path already has a source extension (.md, .txt, .mdx)
       const hrefExt = extname(href).toLowerCase();
       const hasSourceExt = SOURCE_EXTENSIONS.includes(hrefExt);
+      const hasOutputExt = hrefExt === '.html';
       
       // If it has a source extension, check if that exact file exists
+      // If it has .html extension, strip it and look for corresponding source file
       // Otherwise use sourceFileExists which tries multiple extensions
       let fileExists = false;
       if (hasSourceExt) {
         fileExists = existsSync(absoluteSourcePath);
+      } else if (hasOutputExt) {
+        // Strip .html and look for source files (the user linked to the output path)
+        const withoutHtml = absoluteSourcePath.replace(/\.html$/, '');
+        for (const ext of SOURCE_EXTENSIONS) {
+          if (existsSync(withoutHtml + ext)) {
+            absoluteSourcePath = withoutHtml + ext;
+            fileExists = true;
+            break;
+          }
+        }
+        // Also check if it's a directory with an index file (e.g., index.html → index.md)
+        if (!fileExists) {
+          fileExists = sourceFileExists(withoutHtml);
+        }
       } else {
         fileExists = sourceFileExists(absoluteSourcePath);
       }
@@ -441,8 +524,8 @@ export function parseCustomMenu(content, menuDir, sourceRoot) {
         // Normalize path separators for web
         href = href.replace(/\\/g, '/');
         // Convert source extensions to .html
-        if (hasSourceExt) {
-          href = href.replace(/\.(md|txt)$/i, '.html');
+        if (hasSourceExt || existsSync(absoluteSourcePath) && SOURCE_EXTENSIONS.includes(extname(absoluteSourcePath).toLowerCase())) {
+          href = href.replace(/\.(md|mdx|txt)$/i, '.html');
         } else if (!href.match(/\.[a-z]+$/i)) {
           // Ensure it ends with .html if it doesn't have an extension
           // Check if it's likely a folder (ends with /) or file
@@ -454,8 +537,14 @@ export function parseCustomMenu(content, menuDir, sourceRoot) {
           }
         }
       } else {
-        // Source file doesn't exist - this is a non-navigable menu item
-        href = null;
+        // Source file doesn't exist - preserve href as-is so it still renders
+        // as a clickable (though possibly broken) link rather than plain text.
+        // If the href was relative, resolve it to an absolute web path.
+        const resolvedAbsolute = resolve(menuDir, href.startsWith('./') || href.startsWith('../') ? href : './' + href);
+        const resolvedRelative = relative(sourceRoot, resolvedAbsolute);
+        href = '/' + resolvedRelative.replace(/\\/g, '/');
+        // Convert source extensions to .html for web paths
+        href = href.replace(/\.(md|mdx|txt)$/i, '.html');
       }
     }
     
@@ -507,8 +596,8 @@ export function getCustomMenuForFile(filePath, sourceRoot) {
   // Extract frontmatter options
   const { frontmatter, body } = extractMenuFrontmatter(customMenuInfo.content);
   const autoGenerate = frontmatter['auto-generate-menu'] === true || frontmatter['auto-generate-menu'] === 'true';
-  const menuPosition = frontmatter['menu-position'] || 'side';
-  const depth = parseInt(frontmatter['menu-depth'], 10) || 2;
+  const menuPosition = frontmatter['menu-position'] || 'top';
+  const depth = parseInt(frontmatter['menu-depth'], 10) || 10;
   
   let menuData;
   

package/src/helper/imageProcessor.js

@@ -464,8 +464,32 @@ export function transformImageTags(html, imageMap, docUrlPath = '/') {
       const lastAClose = precedingHtml.lastIndexOf('</a>');
       const isInsideAnchor = lastAOpen > lastAClose;
       
+      // Detect per-image no-preview flag:
+      //   Markdown: ![alt](image.jpg?no-preview)  →  ?no-preview in src
+      //   HTML:     <img data-no-preview src="...">  →  data-no-preview attribute
+      const noPreviewQuery = /[?&]no-preview(?:&|$)/.test(src);
+      const noPreviewAttr = /data-no-preview/.test(before + after);
+      const noPreview = noPreviewQuery || noPreviewAttr;
+      
+      // Strip ?no-preview from src so it doesn't appear in output
+      let cleanSrc = src;
+      if (noPreviewQuery) {
+        cleanSrc = cleanSrc
+          .replace(/[?&]no-preview(?=&|$)/, (m) => m[0] === '?' ? '?' : '')
+          .replace(/\?&/, '?')
+          .replace(/\?$/, '');
+      }
+      
+      // Strip data-no-preview attribute from output
+      let cleanBefore = before;
+      let cleanAfter = after;
+      if (noPreviewAttr) {
+        cleanBefore = cleanBefore.replace(/\s*data-no-preview(?:="[^"]*")?\s*/g, ' ');
+        cleanAfter = cleanAfter.replace(/\s*data-no-preview(?:="[^"]*")?\s*/g, ' ');
+      }
+      
       // Normalize src path for lookup
-      let lookupPath = src;
+      let lookupPath = cleanSrc;
       // Remove query strings for lookup
       const queryIndex = lookupPath.indexOf('?');
       if (queryIndex !== -1) {
@@ -490,25 +514,31 @@ export function transformImageTags(html, imageMap, docUrlPath = '/') {
       
       const imageInfo = imageMap.get(lookupPath);
       
-      // Determine full-size URL (use original from imageInfo, or fallback to src)
-      const fullSizeUrl = imageInfo ? imageInfo.original : src;
+      // Determine full-size URL (use original from imageInfo, or fallback to cleaned src)
+      const fullSizeUrl = imageInfo ? imageInfo.original : cleanSrc;
       
-      // Determine the src to use (preview if available, otherwise original)
-      let newSrc = src;
-      if (imageInfo && imageInfo.preview !== imageInfo.original) {
+      // Determine the src to use (preview if available and not suppressed)
+      let newSrc = cleanSrc;
+      if (!noPreview && imageInfo && imageInfo.preview !== imageInfo.original) {
         // Preserve any existing query string (like cache busting) on preview
-        const querySuffix = queryIndex !== -1 ? src.substring(queryIndex) : '';
+        const querySuffix = queryIndex !== -1 ? cleanSrc.substring(queryIndex) : '';
         newSrc = imageInfo.preview + querySuffix;
       }
       
       // Build the new img tag
-      const imgTag = `<img${before}src="${newSrc}"${after}>`;
+      const imgTag = `<img${cleanBefore}src="${newSrc}"${cleanAfter}>`;
       
       // If already inside an anchor tag, just return the updated img tag
       if (isInsideAnchor) {
         return imgTag;
       }
       
+      // If no-preview is set, the image is intentionally full-size — skip the
+      // click-to-view-original wrapper since it would be redundant.
+      if (noPreview) {
+        return imgTag;
+      }
+      
       // Wrap in anchor tag linking to full-size image
       return `<a href="${fullSizeUrl}" target="_blank" class="image-link">${imgTag}</a>`;
     }