@helping-ai-workflow/md2doc 1.0.2 → 1.1.0

package/README.md

@@ -6,11 +6,39 @@ Two global CLIs (`md2html`, `md2pdf`) you can call from any directory.
 
 ## Install
 
+Requires Node.js 18 or higher. The first install pulls puppeteer (≈ 170 MB Chromium download); subsequent installs reuse it.
+
+### Recommended: install via nvm
+
+If you do not yet have Node.js — or your system Node lives under `/usr/local` and `npm install -g` fails with `EACCES` — install Node through [nvm](https://github.com/nvm-sh/nvm) first. nvm puts Node under `~/.nvm`, so global packages never need `sudo`.
+
 ```bash
+sudo apt install -y curl     # Debian / Ubuntu only; skip if curl is already installed
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+source ~/.zshrc              # or: source ~/.bashrc
+nvm install --lts
+nvm use --lts
 npm install -g @helping-ai-workflow/md2doc
 ```
 
-Requires Node.js 18 or higher. The first install pulls puppeteer (≈ 170 MB Chromium download); subsequent installs reuse it.
+### Already have Node.js
+
+```bash
+npm install -g @helping-ai-workflow/md2doc
+```
+
+### Troubleshooting
+
+**`EACCES: permission denied, mkdir '/usr/local/lib/node_modules'`**
+Your system Node is owned by root. Do **not** run `sudo npm install -g` — puppeteer's postinstall would download Chromium as root and break later runs. Instead, switch to nvm using the steps above.
+
+**`Failed to set up chrome ...! Set "PUPPETEER_SKIP_DOWNLOAD" env variable to skip download.`**
+An earlier install left a half-finished Chromium download in `~/.cache/puppeteer`. md2doc ≥ 1.0.3 cleans this automatically; on older versions, clear the cache and retry:
+
+```bash
+rm -rf ~/.cache/puppeteer
+npm install -g @helping-ai-workflow/md2doc
+```
 
 ## Usage
 

package/lib/md2doc.js

@@ -214,6 +214,65 @@ ${itemsHtml}
       .join('');
   }
 
+  function unbreakableRun(s) {
+    // Treat `_` as a break point — identifiers like `pmac_tx_*` are unbreakable in CSS but breakable for classification.
+    const matches = String(s || '').match(/[A-Za-z0-9\-./@:]+/g);
+    if (!matches) return 0;
+    let max = 0;
+    for (const m of matches) if (m.length > max) max = m.length;
+    return max;
+  }
+
+  function cellRawText(cell) {
+    if (!cell) return '';
+    if (Array.isArray(cell.tokens)) return flattenTokenText(cell.tokens);
+    return String(cell.text || '');
+  }
+
+  function classifyColumns(token) {
+    const colCount = (token.header || []).length;
+    const classes = [];
+    for (let i = 0; i < colCount; i++) {
+      const allCells = [];
+      if (token.header && token.header[i]) allCells.push(token.header[i]);
+      const dataCells = [];
+      if (Array.isArray(token.rows)) {
+        for (const row of token.rows) {
+          if (row && row[i]) {
+            allCells.push(row[i]);
+            dataCells.push(row[i]);
+          }
+        }
+      }
+      const allTexts = allCells.map(cellRawText);
+      const dataTexts = dataCells.map(cellRawText);
+      // Header labels (e.g. "Clock Domain") often contain whitespace not representative of cell content; use data rows for the heuristic and fall back to header only when the column has no data.
+      const heuristicTexts = dataTexts.length > 0 ? dataTexts : allTexts;
+      let maxTokenLen = 0;
+      let totalLen = 0;
+      let hasWhitespace = false;
+      let hasSentence = false;
+      for (const t of heuristicTexts) {
+        const r = unbreakableRun(t);
+        if (r > maxTokenLen) maxTokenLen = r;
+        totalLen += t.length;
+        if (/\s/.test(t)) hasWhitespace = true;
+        if (/。|\. /.test(t)) hasSentence = true;
+      }
+      const avgCellLen = heuristicTexts.length ? (totalLen / heuristicTexts.length) : 0;
+
+      // Narrow takes precedence over prose (tie-break: prefer narrow / conservative).
+      if (maxTokenLen <= 12 && !hasWhitespace) {
+        classes.push('col-narrow');
+      } else if (avgCellLen > 40 || hasSentence) {
+        classes.push('col-prose');
+      } else {
+        classes.push('col-default');
+      }
+    }
+    return classes;
+  }
+
   function stripHtmlTags(value) {
     return String(value || '').replace(/<[^>]*>/g, '');
   }
@@ -308,7 +367,6 @@ ${itemsHtml}
     return baseBlockquote(token);
   };
 
-  const baseTable = renderer.table.bind(renderer);
   renderer.table = function(token) {
     collectCellText(token.header);
     if (Array.isArray(token.rows)) {
@@ -316,7 +374,41 @@ ${itemsHtml}
         collectCellText(row);
       }
     }
-    return baseTable(token);
+
+    const classes = classifyColumns(token);
+    const colHtml = classes
+      .map((c) => (c === 'col-default' ? '<col>' : `<col class="${c}">`))
+      .join('');
+    const cellClassAttr = (i) => {
+      const c = classes[i];
+      if (c === 'col-narrow') return ' class="cell-narrow"';
+      if (c === 'col-prose')  return ' class="cell-prose"';
+      return '';
+    };
+    const alignStyle = (cell) => (cell && cell.align)
+      ? ` style="text-align:${cell.align}"`
+      : '';
+
+    const headerCells = (token.header || []).map((cell, i) => {
+      const inner = cell && Array.isArray(cell.tokens)
+        ? this.parser.parseInline(cell.tokens)
+        : '';
+      return `<th${cellClassAttr(i)}${alignStyle(cell)}>${inner}</th>`;
+    }).join('');
+    const headerHtml = `<thead><tr>${headerCells}</tr></thead>`;
+
+    const bodyRows = Array.isArray(token.rows) ? token.rows.map((row) => {
+      const cells = (row || []).map((cell, i) => {
+        const inner = cell && Array.isArray(cell.tokens)
+          ? this.parser.parseInline(cell.tokens)
+          : '';
+        return `<td${cellClassAttr(i)}${alignStyle(cell)}>${inner}</td>`;
+      }).join('');
+      return `<tr>${cells}</tr>`;
+    }).join('') : '';
+    const bodyHtmlPart = `<tbody>${bodyRows}</tbody>`;
+
+    return `<table>\n<colgroup>${colHtml}</colgroup>\n${headerHtml}\n${bodyHtmlPart}\n</table>\n`;
   };
 
   marked.setOptions({ gfm: true, breaks: false, renderer });
@@ -360,6 +452,7 @@ ${itemsHtml}
       <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>
     ${renderTocNodes(tocTree)}
   </nav>
@@ -404,16 +497,52 @@ const html = `<!DOCTYPE html>
   .reader-sidebar {
     position: sticky;
     top: 24px;
-    width: 320px;
+    flex: 0 1 300px;
+    width: clamp(220px, 22vw, 300px);
+    min-width: 220px;
     height: calc(100vh - 48px);
     overflow: hidden;
-    flex: 0 0 320px;
     padding-right: 8px;
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
     gap: 12px;
   }
+  body[data-toc-collapsed] .reader-sidebar {
+    flex-basis: 36px;
+    width: 36px;
+    min-width: 36px;
+    padding-right: 0;
+  }
+  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 {
+    display: none;
+  }
+  body[data-toc-collapsed] #toc-collapse-toggle {
+    transform: rotate(180deg);
+  }
+  #toc-collapse-toggle {
+    margin-left: 0;
+    padding: 2px 8px;
+    font: inherit;
+    font-size: 0.9em;
+    line-height: 1;
+    border: 1px solid #d0d7de;
+    border-radius: 6px;
+    background: #ffffff;
+    color: #57606a;
+    cursor: pointer;
+    transition: transform 0.15s ease;
+  }
+  #toc-collapse-toggle:hover {
+    background: #eef2f6;
+    color: #24292e;
+  }
+  @media (max-width: 1080px) {
+    #toc-collapse-toggle { display: none; }
+  }
   .reader-tools { flex: 0 0 auto; }
   .sidebar-toggle {
     display: none;
@@ -698,6 +827,10 @@ const html = `<!DOCTYPE html>
   .content {
     min-width: 0;
     flex: 1 1 auto;
+  }
+  .content p,
+  .content li,
+  .content blockquote {
     overflow-wrap: anywhere;
     word-break: break-word;
   }
@@ -753,6 +886,36 @@ const html = `<!DOCTYPE html>
   th, td { border: 1px solid #dfe2e5; padding: 7px 14px; text-align: left; }
   th { background: #f6f8fa; font-weight: 600; }
   tr:nth-child(even) { background: #fafbfc; }
+  .content table th,
+  .content table td {
+    overflow-wrap: normal;
+    word-break: normal;
+  }
+  .content table th {
+    white-space: nowrap;
+  }
+  .content table td code,
+  .content table th code {
+    white-space: nowrap;
+  }
+  .content table { table-layout: auto; }
+  .content table col.col-narrow { width: 1%; }
+  .content table col.col-prose { width: auto; }
+  .content table th.cell-narrow,
+  .content table td.cell-narrow { white-space: nowrap; }
+  .content table tbody td:first-child,
+  .content table thead th:first-child {
+    position: sticky;
+    left: 0;
+    z-index: 1;
+    background: #ffffff;
+  }
+  .content table thead th:first-child {
+    background: #f6f8fa;
+  }
+  .content table tbody tr:nth-child(even) td:first-child {
+    background: #fafbfc;
+  }
   blockquote {
     border-left: 4px solid #dfe2e5;
     padding: 0 16px;
@@ -960,6 +1123,25 @@ ${mermaidInitTag}
     });
   }
 
+  function readTocCollapsed() {
+    try { return localStorage.getItem('md2doc.toc.collapsed') === '1'; }
+    catch (_) { return false; }
+  }
+  function writeTocCollapsed(v) {
+    try { localStorage.setItem('md2doc.toc.collapsed', v ? '1' : '0'); }
+    catch (_) { /* private mode / quota — ignore */ }
+  }
+  if (readTocCollapsed()) {
+    document.body.setAttribute('data-toc-collapsed', '');
+  }
+  const tocCollapseBtn = document.getElementById('toc-collapse-toggle');
+  if (tocCollapseBtn) {
+    tocCollapseBtn.addEventListener('click', () => {
+      const nowCollapsed = document.body.toggleAttribute('data-toc-collapsed');
+      writeTocCollapsed(nowCollapsed);
+    });
+  }
+
   const SKIP_SELECTOR = 'svg, .mermaid, .graphviz, script, style';
 
   function buildSnippet(section, query) {

package/package.json

@@ -1,16 +1,25 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
-  "keywords": ["markdown", "html", "pdf", "renderer", "wavedrom", "mermaid", "graphviz"],
+  "keywords": [
+    "markdown",
+    "html",
+    "pdf",
+    "renderer",
+    "wavedrom",
+    "mermaid",
+    "graphviz"
+  ],
   "main": "lib/md2doc.js",
   "bin": {
     "md2html": "bin/md2html.js",
-    "md2pdf":  "bin/md2pdf.js"
+    "md2pdf": "bin/md2pdf.js"
   },
   "files": [
     "lib/",
     "bin/",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],
@@ -22,6 +31,7 @@
     "puppeteer": "^24.15.0"
   },
   "scripts": {
+    "preinstall": "node scripts/preinstall.js",
     "test": "node test/md2doc.test.js"
   },
   "repository": {

package/scripts/preinstall.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+
+// Remove stale puppeteer browser-cache folders that exist but are missing
+// the actual binary. An interrupted prior download leaves @puppeteer/browsers
+// in a state where it sees the version folder and refuses to redownload,
+// failing puppeteer's postinstall with:
+//   The browser folder (.../chrome/<platform>-<ver>) exists but the
+//   executable (.../chrome-<platform>/chrome) is missing
+// We run before puppeteer's postinstall and clean those husks so the
+// download proceeds fresh.
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const BINARY_NAMES = new Set([
+  'chrome',
+  'chrome.exe',
+  'chrome-headless-shell',
+  'chrome-headless-shell.exe',
+  'Google Chrome for Testing',
+]);
+const MIN_BINARY_BYTES = 1_000_000;
+const MAX_DEPTH        = 4;
+
+function hasBinary(rootDir) {
+  const stack = [[rootDir, 0]];
+  while (stack.length) {
+    const [dir, depth] = stack.pop();
+    if (depth > MAX_DEPTH) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isFile() && BINARY_NAMES.has(ent.name)) {
+        try {
+          if (fs.statSync(full).size >= MIN_BINARY_BYTES) return true;
+        } catch { /* ignore */ }
+      } else if (ent.isDirectory()) {
+        stack.push([full, depth + 1]);
+      }
+    }
+  }
+  return false;
+}
+
+function cleanStaleVersionDirs(parentDir) {
+  if (!fs.existsSync(parentDir)) return;
+  let entries;
+  try { entries = fs.readdirSync(parentDir, { withFileTypes: true }); }
+  catch { return; }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const versionDir = path.join(parentDir, ent.name);
+    if (hasBinary(versionDir)) continue;
+    console.log(`[md2doc preinstall] removing stale puppeteer cache: ${versionDir}`);
+    try { fs.rmSync(versionDir, { recursive: true, force: true }); }
+    catch (e) {
+      console.log(`[md2doc preinstall] failed to remove ${versionDir}: ${e.message}`);
+    }
+  }
+}
+
+const cacheRoot = process.env.PUPPETEER_CACHE_DIR
+  || path.join(os.homedir(), '.cache', 'puppeteer');
+
+cleanStaleVersionDirs(path.join(cacheRoot, 'chrome'));
+cleanStaleVersionDirs(path.join(cacheRoot, 'chrome-headless-shell'));