@helping-ai-workflow/md2doc 2.3.1 → 2.4.1

package/README.md

@@ -75,6 +75,29 @@ also pass `--open`.
 | `--version`, `-v` | Print version. |
 | `--help`, `-h` | Print help. |
 
+### Images
+
+Local images referenced from the markdown are resolved against the **markdown file's own
+directory** and inlined into the output as base64 `data:` URIs, so the rendered HTML / PDF
+stays self-contained wherever it is written (the OS temp dir by default) and however it is
+later copied or mailed.
+
+```markdown
+![block diagram](assets/block.png)        <!-- inlined -->
+<img src="assets/block.png" width="400">  <!-- inlined, attributes preserved -->
+![remote](https://example.com/x.png)      <!-- left as a remote URL -->
+```
+
+`srcset` and `<source>` inside `<picture>` are inlined too. Only known image
+extensions are inlined, so `![x](../../id_rsa)` is left alone rather than
+base64'd into a document you may be about to share.
+
+A reference with no file on disk keeps its original `src` and prints
+`[WARN] image not found, left as-is: ...` on stderr; the render still succeeds.
+
+Each reference carries its own copy of the payload, so re-using one large diagram
+in several places grows the HTML accordingly. PDF output is unaffected.
+
 ### Migration from md2html / md2pdf (v1.x → v2.0.0)
 
 | Old | New |

package/lib/md2doc.js

@@ -109,12 +109,195 @@ const mermaidInitTag = `<script type="text/javascript" data-md2doc-diagram-engin
 
 let usesMermaid = false;
 let usesWaveDrom = false;
+let usesMath = false;
+
+// Self-contained KaTeX stylesheet: inline katex.min.css with each woff2 @font-face
+// rewritten to a base64 data: URI and the woff/ttf alternates stripped, so a
+// math-bearing HTML prints offline (and in puppeteer PDF) with no font fetch.
+// Built lazily — only when a document actually contains math.
+function buildKatexStyleTag() {
+  const cssPath = require.resolve('katex/dist/katex.min.css');
+  const fontDir = path.join(path.dirname(cssPath), 'fonts');
+  let css = fs.readFileSync(cssPath, 'utf8');
+  css = css.replace(/url\(fonts\/(KaTeX_[\w-]+)\.woff2\)/g, (_, name) => {
+    const b64 = fs.readFileSync(path.join(fontDir, `${name}.woff2`)).toString('base64');
+    return `url(data:font/woff2;base64,${b64})`;
+  });
+  // Drop the now-redundant woff/ttf src alternates (woff2 is universal in modern
+  // browsers + puppeteer Chromium), so nothing references the on-disk font files.
+  css = css.replace(/,url\(fonts\/[\w-]+\.(?:woff|ttf)\) format\("(?:woff|truetype)"\)/g, '');
+  return `<style data-md2doc-math>${css}</style>`;
+}
+
+// ── Local image assets ───────────────────────────────────────────────────────
+// Image srcs in the markdown are relative to the SOURCE markdown, but the HTML
+// is normally written somewhere else entirely (the OS temp dir by default), so
+// a relative src resolves against the wrong directory and the image silently
+// never loads. Resolve every local reference against the markdown's own
+// directory and inline it as a data: URI — the same self-contained principle
+// the embedded CSS / KaTeX fonts already follow, and the only form that also
+// survives the puppeteer PDF path (which renders from its own temp HTML).
+const SRC_DIR = path.dirname(path.resolve(src));
+const LARGE_ASSET_WARN_BYTES = 4 * 1024 * 1024;
+
+// Doubles as the allowlist: a reference whose extension is not an image is left
+// alone. Without that gate, `![x](../../../.ssh/id_rsa)` would happily base64
+// the file into a document meant to be shared.
+const IMAGE_MIME_BY_EXT = {
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.jfif': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.svg':  'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.bmp':  'image/bmp',
+  '.ico':  'image/x-icon',
+  '.apng': 'image/apng',
+  '.tif':  'image/tiff',
+  '.tiff': 'image/tiff',
+};
+
+const inlinedAssetCache = new Map();
+const skippedAssetWarned = new Set();
+
+// Only a scheme we actually know is treated as remote — a bare `letter+colon`
+// test would misread both a Windows drive (`C:/img.png`) and a filename that
+// merely contains a colon. `//host/x.png` is protocol-relative.
+const EXTERNAL_REF_RE = /^(?:(?:https?|data|file|blob|ftps?|mailto|tel|about|chrome|chrome-extension|moz-extension):|\/\/)/i;
+
+function isExternalRef(href) {
+  return EXTERNAL_REF_RE.test(String(href).trim());
+}
+
+function warnOnce(href, message) {
+  if (skippedAssetWarned.has(href)) return;
+  skippedAssetWarned.add(href);
+  console.error(message);
+}
+
+// Splits `assets/pic.svg?v=2#gear` into its path and its fragment. The query is
+// dropped (it is cache-busting for a fetch that no longer happens); the
+// fragment is kept and re-attached to the data URI, since it selects a view /
+// symbol inside an SVG rather than addressing the file.
+function splitAssetRef(href) {
+  const raw = String(href).trim();
+  const hash = raw.indexOf('#');
+  const withoutHash = hash === -1 ? raw : raw.slice(0, hash);
+  const fragment = hash === -1 ? '' : raw.slice(hash);
+  return { filePart: withoutHash.replace(/\?.*$/, ''), fragment };
+}
+
+function resolveAssetPath(filePart) {
+  if (!filePart) return null;
+  let decoded = filePart;
+  try {
+    decoded = decodeURIComponent(filePart);
+  } catch (_) {
+    // Malformed percent-escapes: probe the raw form only.
+  }
+  const candidates = [];
+  for (const c of [decoded, filePart]) {
+    candidates.push(path.isAbsolute(c) ? c : path.resolve(SRC_DIR, c));
+  }
+  return firstExistingPath(candidates);
+}
+
+// Returns a data: URI, or null when the reference must be left untouched
+// (remote URL, already a data: URI, non-image extension, or no such file).
+function inlineImageSrc(href) {
+  if (!href || isExternalRef(href)) return null;
+  const { filePart, fragment } = splitAssetRef(href);
+  if (!filePart) return null;
+
+  const mime = IMAGE_MIME_BY_EXT[path.extname(filePart).toLowerCase()];
+  if (!mime) {
+    warnOnce(href, `[WARN] not a known image extension, left as-is: ${href}`);
+    return null;
+  }
+
+  const abs = resolveAssetPath(filePart);
+  if (!abs) {
+    warnOnce(href, `[WARN] image not found, left as-is: ${href} (resolved against ${SRC_DIR})`);
+    return null;
+  }
+
+  let uri = inlinedAssetCache.get(abs);
+  if (uri === undefined) {
+    uri = null;
+    try {
+      const stat = fs.statSync(abs);
+      if (!stat.isFile()) throw new Error('not a regular file');
+      if (stat.size > LARGE_ASSET_WARN_BYTES) {
+        console.error(`[WARN] inlining large image (${(stat.size / 1048576).toFixed(1)} MB): ${href}`);
+      }
+      uri = `data:${mime};base64,${fs.readFileSync(abs).toString('base64')}`;
+    } catch (e) {
+      console.error(`[WARN] could not inline image ${href}: ${e.message}`);
+      uri = null;
+    }
+    inlinedAssetCache.set(abs, uri);
+  }
+  return uri ? uri + fragment : null;
+}
+
+// A srcset value is a comma-separated list of `<url> <descriptor>` candidates.
+function inlineSrcsetValue(value) {
+  const parts = String(value).split(',');
+  let changed = false;
+  const rebuilt = parts.map((part) => {
+    const m = part.match(/^(\s*)(\S+)(\s*.*)$/);
+    if (!m) return part;
+    const uri = inlineImageSrc(m[2]);
+    if (!uri) return part;
+    changed = true;
+    return m[1] + uri + m[3];
+  });
+  return changed ? rebuilt.join(',') : null;
+}
+
+// Author-written <img> / <source> tags (specs use them for width= and for
+// <picture>) need the same rewrite. Scoped to markdown-authored HTML chunks
+// only — never run over the whole page, whose bundled mermaid / katex JS also
+// contains '<img' literals.
+// The tag matcher is attribute-aware: a quoted value may legally contain '>',
+// and a plain [^>]* would truncate the tag and miss a src that sits after it.
+const ASSET_TAG_RE = /<(?:img|source)\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+const SRC_ATTR_RE   = /(\s(?:src|srcset)\s*=\s*)(?:(["'])([^"']*)\2|([^\s"'=<>`]+))/gi;
+
+function inlineImagesInTag(tag) {
+  return tag.replace(SRC_ATTR_RE, (match, lead, quote, quoted, bare) => {
+    const raw = (quoted !== undefined ? quoted : bare) || '';
+    const decoded = raw.replace(/&amp;/g, '&');
+    const isSrcset = /srcset\s*=\s*$/i.test(lead);
+    const value = isSrcset ? inlineSrcsetValue(decoded) : inlineImageSrc(decoded);
+    return value ? `${lead}"${value}"` : match;
+  });
+}
+
+function inlineImagesInHtmlChunk(chunk) {
+  if (!chunk || !/<(?:img|source)\b/i.test(chunk)) return chunk;
+  // Step over comments untouched — a commented-out <img> is not displayed, so
+  // inlining it would only bloat the output (or smuggle a file into it).
+  let out = '';
+  let last = 0;
+  HTML_COMMENT_RE.lastIndex = 0;
+  let m;
+  while ((m = HTML_COMMENT_RE.exec(chunk)) !== null) {
+    out += chunk.slice(last, m.index).replace(ASSET_TAG_RE, inlineImagesInTag) + m[0];
+    last = m.index + m[0].length;
+  }
+  return out + chunk.slice(last).replace(ASSET_TAG_RE, inlineImagesInTag);
+}
 
 let bodyHtml;
 let tocHtml = '';
 let serializedSections = '[]';
 try {
   const { marked, Renderer } = require('marked');
+  const katex = require('katex');
 
   const renderer = new Renderer();
   const tocItems = [];
@@ -178,7 +361,7 @@ try {
 
     const itemsHtml = nodes
       .map((node) => {
-        const linkHtml = `<a href="#${node.id}">${escapeHtml(node.text)}</a>`;
+        const linkHtml = `<a href="#${node.id}" title="${escapeHtml(node.text)}">${escapeHtml(node.text)}</a>`;
         const hasChildren = node.children && node.children.length > 0;
 
         if (!hasChildren) {
@@ -305,6 +488,29 @@ ${itemsHtml}
       .replace(/'/g, '&#39;');
   }
 
+  // marked's tokenizer already escapes alt / title (its default image renderer
+  // interpolates both raw), so this must NOT escape them again. Only the src is
+  // ours; everything else — including cleanUrl() on a src we leave alone — stays
+  // marked's job, so non-inlined images render exactly as before.
+  const baseImage = renderer.image.bind(renderer);
+  renderer.image = function(token) {
+    const isObj = (token !== null && typeof token === 'object');
+    const href  = isObj ? (token.href  || '') : (token || '');
+    const title = isObj ? (token.title || '') : (arguments[1] || '');
+    const text  = isObj ? (token.text  || '') : (arguments[2] || '');
+    const uri = inlineImageSrc(href);
+    if (!uri) return baseImage.apply(this, arguments);
+    // A data: URI is base64 (or an already-encoded payload): no quote, no '<'.
+    let out = `<img src="${uri}" alt="${text}"`;
+    if (title) out += ` title="${title}"`;
+    return out + '>';
+  };
+
+  const baseHtml = renderer.html.bind(renderer);
+  renderer.html = function(token) {
+    return inlineImagesInHtmlChunk(baseHtml.apply(this, arguments));
+  };
+
   renderer.code = function(token) {
     // token is either a string (old API) or {text, lang} object (new API)
     const lang = (typeof token === 'object') ? (token.lang || '') : (arguments[1] || '');
@@ -322,6 +528,17 @@ ${itemsHtml}
       // away — diverging from GitHub's escaped-code-block semantics.
       return `\n<div class="mermaid">\n${escapeHtml(code)}\n</div>\n`;
     }
+    if (lang === 'math') {
+      // KaTeX renders synchronously to static HTML (class="katex"); no client
+      // runtime, no async post-pass. throwOnError:false degrades a bad formula
+      // to red error text instead of crashing the whole render.
+      try {
+        return `\n${katex.renderToString(code, { displayMode: true, throwOnError: false })}\n`;
+      } catch (e) {
+        const esc = code.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+        return `<pre><code class="language-math">${esc}</code></pre>\n`;
+      }
+    }
     if (lang === 'dot' || lang === 'graphviz') {
       // Defer rendering to the async bakeGraphviz() post-pass so the
       // synchronous marked() pass stays sync. The dot source is carried as
@@ -454,6 +671,12 @@ ${itemsHtml}
     ],
   });
 
+  // $$…$$ (display) and $…$ (inline) math via KaTeX. marked tokenizes code
+  // spans/fences first, so $ inside code stays literal; the extension's
+  // default no-space-adjacency rules keep prose currency ($5 to $10) unrendered.
+  const markedKatex = require('marked-katex-extension');
+  marked.use(markedKatex({ throwOnError: false }));
+
   // Pre-process the remaining non-standard inline syntax before marked parses
   const escAttr = (s) => String(s)
     .replace(/&/g, '&amp;')
@@ -468,6 +691,9 @@ ${itemsHtml}
     });
 
   bodyHtml = marked.parse(mdPre);
+  // Both the ```math fence and the $/$$ extension emit class="katex" — a single
+  // post-parse scan is the source of truth for conditional CSS injection.
+  usesMath = /class="katex/.test(bodyHtml);
   serializedSections = JSON.stringify(
     sections.map((section) => ({
       id: section.id,
@@ -498,10 +724,12 @@ ${itemsHtml}
   </section>
   <nav class="toc" aria-label="Table of contents" data-reader-toc>
     <div class="toc-header">
-      <span class="toc-title">Contents</span>
-      <button id="toc-expand-all" type="button" aria-label="Expand all">⊞</button>
-      <button id="toc-collapse-all" type="button" aria-label="Collapse all">⊟</button>
-      <button id="toc-collapse-toggle" type="button" aria-label="Collapse table of contents" title="Collapse / expand sidebar">◀</button>
+      <div class="toc-header-actions">
+        <button id="toc-expand-all" type="button" aria-label="Expand all">⊞</button>
+        <button id="toc-collapse-all" type="button" aria-label="Collapse all">⊟</button>
+        <button id="toc-collapse-toggle" type="button" aria-label="Collapse table of contents" title="Collapse / expand sidebar">◀</button>
+      </div>
+      <div class="toc-breadcrumb" data-toc-breadcrumb aria-label="Current location"></div>
     </div>
     ${renderTocNodes(tocTree)}
   </nav>
@@ -566,7 +794,7 @@ const html = `<!DOCTYPE html>
   body[data-toc-collapsed] .reader-tools,
   body[data-toc-collapsed] .search-results,
   body[data-toc-collapsed] .toc > .toc-list,
-  body[data-toc-collapsed] .toc-title {
+  body[data-toc-collapsed] .toc-breadcrumb {
     display: none;
   }
   body[data-toc-collapsed] #toc-collapse-toggle {
@@ -586,6 +814,9 @@ const html = `<!DOCTYPE html>
     margin-bottom: 0;
     justify-content: center;
   }
+  body[data-toc-collapsed] .toc-header-actions {
+    justify-content: center;
+  }
   #toc-collapse-toggle {
     margin-left: 0;
     padding: 2px 8px;
@@ -675,10 +906,45 @@ const html = `<!DOCTYPE html>
   .search-results-header,
   .toc-header {
     display: flex;
-    align-items: center;
-    gap: 6px;
+    flex-direction: column;
+    align-items: stretch;
+    gap: 4px;
     margin-bottom: 8px;
   }
+  .toc-header-actions {
+    flex: 0 0 auto;
+    display: flex;
+    gap: 6px;
+    justify-content: flex-end;
+  }
+  /* Sticky breadcrumb: stacked ancestor chain of the current scroll position.
+     Each row is single-line + ellipsis; full text on hover via title=. */
+  .toc-breadcrumb {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+  }
+  .toc-breadcrumb a {
+    display: block;
+    max-width: 100%;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    color: #57606a;
+    text-decoration: none;
+    font-size: 0.82em;
+    line-height: 1.55;
+    box-sizing: border-box;
+  }
+  .toc-breadcrumb a:hover {
+    color: #0969da;
+  }
+  .toc-breadcrumb a.breadcrumb-current {
+    color: #0b57d0;
+    font-weight: 700;
+  }
   .search-results-title,
   .toc-title {
     font-size: 0.78rem;
@@ -804,18 +1070,26 @@ const html = `<!DOCTYPE html>
     margin-top: 2px;
   }
   .toc-item {
-    margin: 1px 0;
+    margin: 0;
   }
   .toc a {
-    display: inline-block;
+    display: block;
     max-width: 100%;
     color: #57606a;
     text-decoration: none;
-    padding: 4px 0 4px 0;
-    overflow-wrap: anywhere;
-    word-break: break-word;
+    padding: 2px 0;
+    line-height: 1.4;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
     box-sizing: border-box;
   }
+  /* Parent rows put the anchor inside a flex <summary>; default flex min-width
+     is auto, which would block ellipsis. Allow the anchor to shrink + clip. */
+  .toc summary > a {
+    min-width: 0;
+    flex: 0 1 auto;
+  }
   .toc summary {
     min-width: 0;
   }
@@ -845,7 +1119,7 @@ const html = `<!DOCTYPE html>
     display: flex;
     align-items: flex-start;
     gap: 6px;
-    padding: 2px 0;
+    padding: 0;
   }
   .toc summary::-webkit-details-marker {
     display: none;
@@ -1056,6 +1330,7 @@ const html = `<!DOCTYPE html>
     a[href]:after { content: none; }
   }
 </style>
+${usesMath ? buildKatexStyleTag() : ''}
 </head>
 <body>
 <button class="sidebar-toggle" id="sidebar-toggle" type="button" aria-label="Toggle sidebar" aria-expanded="false">☰</button>
@@ -1120,6 +1395,43 @@ ${mermaidInitTag}` : ''}
     return String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
   }
 
+  const breadcrumbEl = document.querySelector('[data-toc-breadcrumb]');
+  const sectionIndexById = new Map(sections.map((section, i) => [section.id, i]));
+
+  // Sticky breadcrumb: the ancestor chain (shallow→deep) of the active section.
+  // For each decreasing depth, take the nearest preceding section, then append
+  // the active section itself. Rendered as stacked, indented, clickable rows.
+  function renderBreadcrumb(sectionId) {
+    if (!breadcrumbEl) return;
+    if (!sectionIndexById.has(sectionId)) {
+      breadcrumbEl.innerHTML = '';
+      return;
+    }
+    const idx = sectionIndexById.get(sectionId);
+    const chain = [];
+    let need = sections[idx].depth;
+    for (let i = idx; i >= 0 && need >= 1; i--) {
+      if (sections[i].depth <= need) {
+        chain.unshift(sections[i]);
+        need = sections[i].depth - 1;
+      }
+    }
+    if (!chain.length) {
+      breadcrumbEl.innerHTML = '';
+      return;
+    }
+    const minDepth = chain[0].depth;
+    breadcrumbEl.innerHTML = chain
+      .map((section, i) => {
+        const indent = (section.depth - minDepth) * 10;
+        const cls = i === chain.length - 1 ? ' class="breadcrumb-current"' : '';
+        const title = escapeHtml(section.title);
+        return '<a href="#' + section.id + '"' + cls + ' title="' + title +
+          '" style="padding-left:' + indent + 'px">' + title + '</a>';
+      })
+      .join('');
+  }
+
   function expandTocAncestors(link) {
     let node = link && link.closest('details');
     while (node) {
@@ -1153,6 +1465,7 @@ ${mermaidInitTag}` : ''}
       previous.classList.remove('is-active');
     }
     readerState.activeSectionId = sectionId;
+    renderBreadcrumb(sectionId);
     const next = tocLinks.get(sectionId);
     if (next) {
       next.classList.add('is-active');
@@ -1178,6 +1491,12 @@ ${mermaidInitTag}` : ''}
     headingNodes.forEach((node) => observer.observe(node));
   }
 
+  // Paint the breadcrumb immediately so the header is populated before the
+  // first IntersectionObserver callback fires.
+  if (sections[0]) {
+    renderBreadcrumb(sections[0].id);
+  }
+
   const allTocDetails = () => Array.from(document.querySelectorAll('.toc details'));
   const expandAllBtn = document.getElementById('toc-expand-all');
   if (expandAllBtn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
   "keywords": [
     "markdown",
@@ -27,14 +27,16 @@
   },
   "dependencies": {
     "@hpcc-js/wasm-graphviz": "1.22.0",
+    "katex": "^0.16.47",
     "marked": "^14.1.0",
+    "marked-katex-extension": "^5.1.10",
     "mermaid": "11.15.0",
     "puppeteer": "^24.15.0",
     "wavedrom": "3.5.0"
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",
-    "test": "node test/md2doc.test.js && node test/cli.test.js && node test/code-operator.test.js"
+    "test": "node test/md2doc.test.js && node test/images.test.js && node test/cli.test.js && node test/code-operator.test.js"
   },
   "repository": {
     "type": "git",