@helping-ai-workflow/md2doc 2.3.1 → 2.4.0

package/lib/md2doc.js

@@ -109,12 +109,32 @@ 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>`;
+}
 
 let bodyHtml;
 let tocHtml = '';
 let serializedSections = '[]';
 try {
   const { marked, Renderer } = require('marked');
+  const katex = require('katex');
 
   const renderer = new Renderer();
   const tocItems = [];
@@ -178,7 +198,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) {
@@ -322,6 +342,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 +485,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 +505,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 +538,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 +608,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 +628,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 +720,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 +884,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 +933,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 +1144,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 +1209,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 +1279,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 +1305,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.0",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
   "keywords": [
     "markdown",
@@ -27,7 +27,9 @@
   },
   "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"