md-preview-cli-plus 1.0.6 → 1.1.0

package/README.md

@@ -8,7 +8,7 @@ Markdown 实时预览 + 导出工具
 
 CLI + Web + Markdown 三位一体
 
-由于CLI对系统兼容性要求高，选择 CommonJS 模块化方式
+由于 CLI 对系统兼容性要求高，服务端选择 CommonJS 模块化方式，浏览器采用 ESM
 
 # Getting Started
 
@@ -36,7 +36,7 @@ npx md-preview-cli-plus <file_path> [options]
 **Hot Module Replacement (HMR)** Similar to Vite's HMR: wraps `socket.io` for both client and server.
 
 - The browser uses `useSocket()` to listen for server messages.
-- On notification, the page auto-refreshes.
+- Performance optimization for large files: The page partially updates upon receiving a notification.+ debounce
 - The server watches file changes and pushes updates to the browser.
 
 **HTML Export Feature** Supports `--export` flag to save rendered content as an HTML file.
@@ -47,14 +47,20 @@ npx md-preview-cli-plus <file_path> [options]
 
 - Supports custom plugins
 - Configuration via `.previewrc` file and CLI arguments
+```json
+//.previewrc
+{
+  "theme": "default",
+  "pluginsFolder": [//loading all plugins under these folders
+    "./plugins"
+  ]
+}
+```
 - CLI arguments take precedence over config file
+- **Fault Tolerance** If a plugin throws an error, it will be ignored to prevent breaking the core functionality.
 
 **Packaging & Distribution** Published as an npm package.
 
-- Supports direct usage via `npx md-preview-cli ...` without installation.
-
-**Fault Tolerance** If a plugin throws an error, it will be ignored to prevent breaking the core functionality.
-
 # 🔌 Plugin System
 
 1. **Multiple Integration Options:**
@@ -65,20 +71,22 @@ npx md-preview-cli-plus <file_path> [options]
    - `init`
    - `beforeRender`
    - `afterRender`
-
+<hr>
 # 功能细化
 
 1. 构建CLI 采用commander 解析参数、增加帮助信息--help、版本控制-V --version、错误处理
 2. 文件监听变化 chokidar 跨平台兼容性好 低耗能
 3. 打开open 打开各种文件程序 跨平台兼容性好
 4. 打造彩色终端 🌈chalk，引入代码高亮 highlight.js
-5. 热刷新HMR：（类似 Vite）封装socket.io客户端和服务端，浏览器使用useSocket()监听服务端消息，有通知则刷新页面，服务端监听文件变化并通知浏览器页面更新
+5. 热刷新HMR：（类似 Vite）封装socket.io客户端和服务端，浏览器使用useSocket()监听服务端消息，有通知则局部更新页面 ~~（借助morphdom做DOM diff算法）~~ ，服务端监听文件变化并通知浏览器页面更新
+性能优化：
+(1)拆分为逻辑块，手写逻辑块 diff算法对比（按照key比较），将修改块发送给客户端，客户端通过增删逻辑对比替换
+(2)更新逻辑的防抖处理：100ms等待时间
 6. 导出 HTML 功能：增加 --export 参数保存 HTML 文件
 7. 多主题支持：通过 --theme=dark 选择不同样式、支持自定义主题（放在styles文件夹下，代码参考default.css）
-8. 插件机制：支持自定义插件及其生命周期钩子、高灵活度配置，支持插件配置文件.previewrc+CLI参数优先级控制
-9. 打包发布：发布为 NPM 包，支持 `npx md-preview-cli ...`无需下载，直接使用
-10. 容错机制：如果某插件有错误，无视该插件；
-11. 后续：结合图床、富文本编辑、插件沙箱机制、vitest单元测试
+8. 插件机制：支持自定义插件及其生命周期钩子、高灵活度配置，支持插件配置文件.previewrc（一键配置加载文件夹下所有插件）+CLI参数优先级控制；容错机制：如果某插件有错误，无视该插件；
+9. 打包发布：已发布为 NPM 包
+10. 后续：微前端结合文档管理器（传入文件夹）、图床、富文本编辑、插件沙箱机制、vitest单元测试
 
 # 插件机制
 
@@ -95,8 +103,7 @@ md-preview/
 │   ├── pluginManager.js           # 插件加载器
 │   ├── preview.js          # 启动本地服务
 │   └── renderMarkdown.js   # Markdown 渲染函数
-│   └── loadConfig.js   # 读取配置文件 .previewrc
-│   └── loader.js   # 读取某文件夹下所有插件
+│   └── utils.js   # 多个工具函数，读取配置文件 .previewrc、读取某文件夹下所有插件
 ├── public/
 │   └── hmrServer.js #hmr socket服务器
 │   └── useSocket.js #hmr socket客户端
@@ -105,7 +112,6 @@ md-preview/
 │   └── dark.css           # 暗黑主题样式
 ├── README.md
 ├── package.json
-└── .gitignore
-plugins/
-├── copyright-plugin.js      # 示例插件 影响最底部文字 可直接删除
+├── plugins/
+│   ├── copyright-plugin.js      # 示例插件 影响最底部文字 可直接删除
 ```

package/bin/cli.js

@@ -4,8 +4,7 @@ const { program } = require('commander');
 const path = require('path');
 const startPreview = require('../lib/preview');
 const pluginManager = require('../lib/pluginManager');
-const loadConfig = require('../lib/loadConfig');
-const loadPlugins = require('../lib/loader');
+const { loadConfig, loadPlugins } = require('../lib/utils');
 
 //帮助信息自动生成，不需要手动写
 //默认命令触发条件就是和基本信息分开
@@ -23,7 +22,7 @@ program
   .option('--theme <theme>', `${theme_d}`, 'default')
   .option('--export <path>', `${export_d}`, null)
   //修改CLI支持--plugin参数 可多个
-  .option('--plugin <path...>', `${plugin_d}`) //...是commander里的rest参数
+  .option('--plugin [plugin_path1,plugin_path2,...]', `${plugin_d}`) //...是commander里的rest参数
   .action((file, options) => {
     //console.log(options)
 

package/lib/preview.js

@@ -1,6 +1,6 @@
 const express = require('express');
 const fs = require('fs');
-const markdownToHtml = require('./renderMarkdown');
+const { markdownToHtml } = require('./renderMarkdown');
 const hmrServer = require('../public/hmrServer');
 const open = require('open');
 const chalk = require('chalk');
@@ -10,14 +10,14 @@ function startPreview(filePath, options, pluginManager) {
   const app = express();
   const port = options.port || 3000;
 
+  let { htmlBlocks, html } = markdownToHtml(filePath, options.theme, options.port, pluginManager);
   app.get('/', (req, res) => {
-    let html = markdownToHtml(filePath, options.theme, options.port, pluginManager);
-    html = pluginManager.allAfterRender(html, options.theme) ?? html;
     if (options.export) {
       const exportPath = path.resolve(process.cwd(), options.export);
       fs.writeFileSync(exportPath, html);
       console.log(chalk.green(`✅ HTML exported to: ${exportPath}`));
     }
+    html = pluginManager.allAfterRender(html, options.theme) ?? html;
     res.send(html);
   });
 
@@ -29,7 +29,7 @@ function startPreview(filePath, options, pluginManager) {
     open(`http://localhost:${port}`);
   }); //返回http.Server对象
 
-  hmrServer(server, filePath);
+  hmrServer(server, filePath, options.theme, pluginManager, htmlBlocks);
 }
 
 module.exports = startPreview;

package/lib/renderMarkdown.js

@@ -1,19 +1,173 @@
-const fs = require('fs');
 const markdownIt = require('markdown-it');
+const fs = require('fs');
+const crypto = require('crypto');
+function generateHash(content) {
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+function splitBlocks(mdText) {
+  //按逻辑块分组 正确渲染多行结构
+  /*逻辑块汇总
+段落（连续非空文本行）
+标题（# 开头）
+代码块（``` 包裹）
+表格（包含 | 且有 |---| 分隔行）
+引用块（> 开头）
+列表项（- / * / 1. 开头）
+水平线（---、*** 等）
+空行（作为块的分隔）
+  */
+  const lines = mdText.split('\n');
+  const blocks = [];
+  let buffer = [];
+  let blockType = null;
+  let inCodeBlock = false; //是否在代码块中
+  let codeBlockFence = '';
+  function pushBuffer(index) {
+    if (buffer.length) {
+      let content = buffer.join('\n');
+      blocks.push({
+        type: blockType || 'paragraph',
+        content,
+        index, //逻辑块所在的结束行号
+        key: generateHash(`${blockType}${content}`), //生成唯一标识符
+      });
+      mapKey = [];
+      buffer = [];
+      blockType = null;
+    }
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // --- 处理代码块 ---
+    if (/^```/.test(line)) {
+      if (!inCodeBlock) {
+        pushBuffer(i - 1); // 之前的结束
+        inCodeBlock = true;
+        codeBlockFence = line.trim();
+        blockType = 'code';
+        buffer.push(line);
+      } else {
+        buffer.push(line);
+
+        pushBuffer(i); // 整个代码块结束
+        inCodeBlock = false;
+        codeBlockFence = '';
+        continue;
+      }
+      continue;
+    }
+    if (inCodeBlock) {
+      buffer.push(line);
+
+      continue;
+    }
+
+    // --- 空行：结束当前块 ---
+    if (line.trim() === '') {
+      pushBuffer(i);
+      continue;
+    }
+
+    // --- 处理标题 ---
+    if (/^#{1,6} /.test(line)) {
+      pushBuffer(i - 1); // 之前的结束
+      blockType = 'heading';
+      buffer.push(line);
+
+      pushBuffer(i);
+      continue;
+    }
+    // --- 处理引用 ---
+    if (/^\s*>/.test(line)) {
+      //引用符号前面可以只有空白符
+      if (blockType !== 'blockquote') {
+        pushBuffer(i - 1);
+        blockType = 'blockquote';
+      }
+      buffer.push(line);
+
+      continue;
+    }
+    // --- 处理列表 ---
+    if (/^\s*[-*+] /.test(line) || /^\s*\d+\. /.test(line)) {
+      if (blockType !== 'list') {
+        pushBuffer(i - 1);
+        blockType = 'list';
+      }
+      buffer.push(line);
+
+      continue;
+    }
+    // --- 处理表格 --- \s* 表示可有可无空格
+    if (/^\s*\|.*\|\s*$/.test(line)) {
+      if (blockType !== 'table') {
+        pushBuffer(i - 1);
+        blockType = 'table';
+      }
+      buffer.push(line);
 
+      continue;
+    }
+    // --- 处理分割线 ---
+    if (/^---+$/.test(line) || /^\*\*\*+$/.test(line)) {
+      pushBuffer(i - 1);
+      blockType = 'hr';
+      buffer.push(line);
+
+      pushBuffer(i);
+      continue;
+    }
+
+    // --- 默认处理为段落 ---
+    if (blockType !== 'paragraph') {
+      pushBuffer(i - 1);
+      blockType = 'paragraph';
+    }
+    buffer.push(line);
+  }
+
+  pushBuffer(lines.length); // 最后剩下的也加入
+  return blocks;
+}
+function mergeHtml(htmlBlocks, theme, pluginManager) {
+  let html = htmlBlocks.map((block) => block.html).join('');
+  // renderHtml = pluginManager.allAfterRender(html,theme) ?? html;
+  // return renderHtml;
+  return html;
+}
+function preProcessing(filePath, theme, pluginManager) {
+  let markdownContent = fs.readFileSync(filePath, 'utf-8');
+  markdownContent = pluginManager.allBeforeRender(markdownContent, theme) ?? markdownContent;
+  let splitedMd = splitBlocks(markdownContent);
+  let htmlBlocks = [];
+  for (const idx in splitedMd) {
+    const block = splitedMd[idx];
+    block.html = md.render(block.content);
+    htmlNode = {
+      ...block,
+      idx,
+      html: `<div 
+      data-key="${block.key}"
+      data-idx="${idx}" 
+      data-index="${block.index}" data-type="${block.type}">${block.html}</div>`,
+    };
+    htmlBlocks.push(htmlNode); //传入辅助信息
+  }
+  return htmlBlocks;
+}
 function markdownToHtml(filePath, theme = 'default', port, pluginManager) {
-  const md = new markdownIt({
+  md = new markdownIt({
     html: true,
     linkify: true, //自动识别链接文本
     typographer: true, //排版符号美化
   });
-
-  let markdownContent = fs.readFileSync(filePath, 'utf-8');
-  markdownContent = pluginManager.allBeforeRender(markdownContent, theme) ?? markdownContent;
-
-  let htmlContent = md.render(markdownContent);
-
-  return `
+  let htmlBlocks = preProcessing(filePath, theme, pluginManager);
+  let renderHtml = mergeHtml(htmlBlocks, theme, pluginManager);
+  return {
+    htmlBlocks,
+    html: `
 <!DOCTYPE html>
 <html lang="en">
 <head>
@@ -23,8 +177,8 @@ function markdownToHtml(filePath, theme = 'default', port, pluginManager) {
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.6.0/styles/github-dark.min.css">
 </head>
 <body>
-  <div class="content">
-    ${htmlContent}
+  <div class="content" id="oldHtml">
+    ${renderHtml}
   </div>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.6.0/highlight.min.js"></script>
   <script>
@@ -32,17 +186,11 @@ function markdownToHtml(filePath, theme = 'default', port, pluginManager) {
   </script>
   <script type="module">
     import { useSocket } from '/useSocket.js'
-
-    useSocket({
-      serverUrl: 'http://localhost:${port}',
-      onUpdate: (html) => {
-        //document.querySelector('.content').innerHTML = html
-        location.reload()
-      }
-    })
+    useSocket('http://localhost:${port}')
   </script>
 </body>
-</html>`;
+</html>`,
+  };
 }
 
-module.exports = markdownToHtml;
+module.exports = { preProcessing, mergeHtml, markdownToHtml };

package/lib/{loader.js → utils.js}

@@ -1,9 +1,8 @@
-//loader.js
-//把配置的插件都加载放入并返回
-const path = require('path');
 const fs = require('fs');
+const path = require('path');
 
 function loadPlugins(folder_path) {
+  //加载文件夹下所有插件
   let plugins = [];
   //把folder_path目录下的插件注册完
   if (Array.isArray(folder_path)) {
@@ -27,4 +26,22 @@ function loadPlugins(folder_path) {
   return plugins;
 }
 
-module.exports = loadPlugins;
+function loadConfig() {
+  //配置读取模块
+  const configPath = path.resolve(process.cwd(), '.previewrc');
+  if (!fs.existsSync(configPath)) return {};
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const config = JSON.parse(raw);
+    return config;
+  } catch (e) {
+    console.warn('⚠️ Failed to load .previewrc :', e.message);
+    return {};
+  }
+}
+
+module.exports = {
+  loadConfig,
+  loadPlugins,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md-preview-cli-plus",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "md real-time preview + export",
   "keywords": [
     "markdown",
@@ -38,6 +38,7 @@
     "chokidar": "^4.0.3",
     "commander": "^14.0.0",
     "express": "^5.1.0",
+    "lodash.debounce": "^4.0.8",
     "markdown-it": "^14.1.0",
     "open": "^8.4.0",
     "socket.io": "^4.8.1"
@@ -49,5 +50,16 @@
     "husky": "^9.1.7",
     "lint-staged": "^16.1.2",
     "prettier": "^3.6.2"
-  }
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "plugins/",
+    "public/",
+    "styles/",
+    ".editorconfig",
+    ".previewrc",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/plugins/copyright-plugin.js

@@ -9,6 +9,12 @@ module.exports = {
 
   // 渲染为 HTML 后调用，可修改 HTML 字符串
   afterRender(html, options) {
-    return html + `<footer><p style="text-align:center;color:#aaa;">© 2025 </p></footer>`;
+    if (html.includes('<footer>')) {
+      return html; // 如果已经有 footer，则不添加
+    }
+    return html.replace(
+      '</body>',
+      `<footer><p style="text-align:center;color:#aaa;">© 2025 </p></footer></body>`
+    );
   },
 };

package/public/hmrServer.js

@@ -1,8 +1,41 @@
 const { Server } = require('socket.io');
 const chokidar = require('chokidar');
 const chalk = require('chalk');
+const { preProcessing } = require('../lib/renderMarkdown');
+const debounce = require('lodash.debounce'); // 防抖函数
+function NodeDiff(oldBlocks, newBlocks) {
+  //按key比较
+  //console.log(JSON.stringify(newBlocks));
+  //console.log(Array.isArray(oldBlocks),Array.isArray(newBlocks));
+  const oldMap = new Map(oldBlocks.map((b) => [b.key, b]));
+  const newMap = new Map(newBlocks.map((b) => [b.key, b]));
 
-function hmrServer(server, filePath) {
+  const added = [];
+  const updated = [];
+  const deleted = [];
+
+  // 找出新增和更新的
+  for (const [key, newBlock] of newMap) {
+    //console.log(key,'666',oldMap.get(key))
+    const oldBlock = oldMap.get(key);
+    if (!oldBlock) {
+      added.push(newBlock);
+    }
+    // else if (JSON.stringify(oldBlock.content) !== JSON.stringify(newBlock.content)) {
+    //   updated.push(newBlock);
+    // }
+  }
+
+  // 找出被删除的
+  for (const [key, oldBlock] of oldMap) {
+    if (!newMap.has(key)) {
+      deleted.push(oldBlock);
+    }
+  }
+  return { added, updated, deleted };
+}
+function hmrServer(server, filePath, theme, pluginManager, oldBlocks) {
+  //旧html块
   const watcher = chokidar.watch(filePath);
   const io = new Server(server, {
     cors: { origin: '*' },
@@ -10,9 +43,24 @@ function hmrServer(server, filePath) {
   io.on('connection', (socket) => {
     //console.log('connect successfully')
   });
-  watcher.on('change', () => {
-    console.log(chalk.green('📄 Markdown file updated, refreshing page automatically.'));
-    io.emit('update');
-  });
+  let oldHtmlBlocks = oldBlocks;
+  watcher
+    .on('ready', () => {
+      // console.log('ready!!!!')
+      // setTimeout(() => {
+      //   io.emit('init', pluginManager, theme);
+      // }, 1000); // 等客户端连接稳定后再发
+    })
+    .on(
+      'change',
+      debounce(() => {
+        console.log(chalk.cyan('📄 Markdown file updated and this page will update partially.'));
+        newHtmlBlocks = preProcessing(filePath, theme, pluginManager);
+        changedBlocks = NodeDiff(oldHtmlBlocks, newHtmlBlocks);
+        //console.log(JSON.stringify(changedBlocks));
+        io.emit('update', changedBlocks, pluginManager, theme);
+        oldHtmlBlocks = newHtmlBlocks; // 更新旧的逻辑块
+      }, 100)
+    ); //防抖处理：如果有变化 则需要等待100ms后再执行一次更新逻辑
 }
 module.exports = hmrServer;

package/public/useSocket.js

@@ -1,7 +1,67 @@
+//ESM模块化
 // useSocket.js（浏览器端模块，支持原生或 Vite 项目）
 import { io } from 'https://cdn.socket.io/4.7.5/socket.io.esm.min.js';
+//import morphdom from 'https://cdn.jsdelivr.net/npm/morphdom@2.6.1/dist/morphdom-esm.js';
+function htmlStringToNode(htmlStr) {
+  const template = document.createElement('template'); //安全解析DOM结构 支持所有浏览器
+  template.innerHTML = htmlStr.trim(); // 去除空格，避免空文本节点
+  return template.content.firstChild;
+}
+function applyDiff({ added = [], updated = [], deleted = [] }, container) {
+  const keyToElement = new Map();
+  // 先缓存当前 DOM 中的所有 block 节点
+  container.querySelectorAll('[data-key]').forEach((el) => {
+    keyToElement.set(el.dataset.key, el);
+  });
+
+  // 1. 删除
+  deleted.forEach((block) => {
+    const el = keyToElement.get(block.key);
+    if (el) el.remove();
+  });
 
-export function useSocket({ serverUrl, onUpdate }) {
+  // 2. 更新 不可能有完全一样的key，因为key的组成是type+content 如果有变化则content不可能相同
+  // updated.forEach(block => {
+  //   const oldEl = keyToElement.get(block.key);
+  //   if (oldEl) {
+  //     const newEl = htmlStringToNode(block.html);
+  //     morphdom(oldEl, newEl, {//按照key来找到旧节点 无论顺序如何改变
+  //       getNodeKey: node => node.dataset?.key ?? null
+  //     });
+  //   }
+  // });
+
+  // 3. 新增
+  added.forEach((block) => {
+    const newEl = htmlStringToNode(block.html);
+
+    // 插入位置：用 idx 升序插入
+    const all = Array.from(container.querySelectorAll('[data-key]'));
+    const idx = block.idx;
+
+    let inserted = false;
+    for (let i = 0; i < all.length; i++) {
+      const elIdx = parseInt(all[i].dataset.idx);
+      if (elIdx > idx) {
+        container.insertBefore(newEl, all[i]);
+        inserted = true;
+        break;
+      }
+    }
+
+    if (!inserted) {
+      container.appendChild(newEl);
+    }
+  });
+}
+
+// function OneParentNode(html) {//morphdom需要一个父节点
+//   const div = document.createElement('div');
+//   div.id = 'oldHtml';
+//   div.innerHTML = html;
+//   return div;
+// }
+export function useSocket(serverUrl) {
   const socket = io(serverUrl);
 
   socket.on('connect', () => {
@@ -13,11 +73,18 @@ export function useSocket({ serverUrl, onUpdate }) {
   });
 
   // 接收后端推送的 HTML 内容
-  socket.on('update', (htmlContent) => {
-    console.log('📥 收到 update 事件');
-    if (typeof onUpdate === 'function') {
-      onUpdate(htmlContent);
-    }
+  // socket.on('init',(pluginManager,theme)=>{
+  //   console.log(pluginManager,theme)
+  //   let node=document.getElementById('oldHtml');
+  //   let html=node.innerHTML;
+  //   node.innerHTML=pluginManager.allAfterRender(html,theme) ?? html;
+  // })
+  socket.on('update', (changedBlocks, pluginManager, theme) => {
+    console.log('📥 收到 update 事件', changedBlocks);
+    applyDiff(changedBlocks, document.getElementById('oldHtml'));
+
+    //morphdom(document.getElementById('oldHtml'), OneParentNode(newHtml));
+    // 自动把 old 中的 DOM 节点，变更为 new 的内容，只更新必要的差异部分。
   });
 
   return socket;

package/.github/workflows/main.yml

@@ -1,31 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - 'v*'  # 仅当发布 tag，如 v1.0.0 时触发
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repo
-        uses: actions/checkout@v3
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          registry-url: 'https://registry.npmjs.org/'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run
-        run: npm run  # 如果你没有 build 步骤可以删掉
-
-      - name: Publish to npm
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/lib/loadConfig.js

@@ -1,20 +0,0 @@
-//配置读取模块 lib/loadConfig.js
-
-const fs = require('fs');
-const path = require('path');
-
-function loadConfig() {
-  const configPath = path.resolve(process.cwd(), '.previewrc');
-  if (!fs.existsSync(configPath)) return {};
-
-  try {
-    const raw = fs.readFileSync(configPath, 'utf-8');
-    const config = JSON.parse(raw);
-    return config;
-  } catch (e) {
-    console.warn('⚠️ Failed to load .previewrc :', e.message);
-    return {};
-  }
-}
-
-module.exports = loadConfig;