zhangdocs 1.1.31 → 1.1.34

package/.bin/zhangdocs.js

@@ -18,9 +18,11 @@ commander
     .option('-b, build', 'Markdown produces static pages document.')
     .option('-w, watch', 'Listener "md" file is automatically generated pages.')
     .option('-s, server', 'Open local static html server.')
+    .option('-d, --daemon', 'Run server in background (use with -s). Close terminal safely.')
+    .option('--stop', 'Stop background server started with -s -d.')
     .option('-c, clean', 'Clear the generate static files.')
     .option('-t, theme', 'Choose a theme.')
-    .option('-d, deploy', 'Publish to a gh-pages branch on GitHub.')
+    .option('--deploy', 'Publish to a gh-pages branch on GitHub.')
     .option('-p, pdf', 'PDF generation.')
 
 commander
@@ -31,9 +33,11 @@ commander
         log('    $ zhangdocs init [path] ');
         log('    $ zhangdocs init [path] -C ~/zhangdocs/');
         log('    $ zhangdocs watch');
-        log('    $ zhangdocs server');
-        log('    $ zhangdocs clean');
-        log('    $ zhangdocs deploy');
+        log('    $ doc -s');
+        log('    $ doc -s -d          # server in background');
+        log('    $ doc -s --stop      # stop background server');
+        log('    $ doc clean');
+        log('    $ doc --deploy');
         log('    $ zhangdocs theme');
         log('    $ zhangdocs -t ~/git/zhangdocs-theme-slate/');
 

package/.zhangdocs/server.log

@@ -0,0 +1 @@
+[2026-05-16T11:05:28.652Z] doc server started (PID 34124)

package/README.md

@@ -85,11 +85,25 @@ doc build
 ### 4. 启动开发服务器
 
 ```bash
-doc server
+doc -s
 ```
 
 这将启动一个本地服务器，并监听文件变化自动重新构建。
 
+后台运行（关闭命令行窗口后服务仍继续）：
+
+```bash
+doc -s -d
+```
+
+停止后台服务：
+
+```bash
+doc -s --stop
+```
+
+日志文件位于项目目录下的 `.zhangdocs/server.log`。
+
 ### 5. 监听文件变化
 
 ```bash
@@ -105,9 +119,11 @@ doc watch
 | `doc init` | 初始化项目 |
 | `doc build` | 构建静态页面 |
 | `doc watch` | 监听文件变化并自动构建 |
-| `doc server` | 启动开发服务器（包含 watch 功能） |
+| `doc -s` | 启动开发服务器（包含 watch 功能） |
+| `doc -s -d` | 后台启动开发服务器，可关闭终端 |
+| `doc -s --stop` | 停止后台开发服务器 |
 | `doc clean` | 清理构建文件 |
-| `doc deploy` | 部署文档 |
+| `doc --deploy` | 部署文档 |
 | `doc theme` | 主题管理 |
 | `doc -V` | 查看版本号 |
 

package/index.js

@@ -8,7 +8,7 @@ var pdf = require('./lib/pdf');
 var theme = require('./lib/theme');
 var color = require('colors-cli');
 var path = require('path');
-var server = require('ssr');
+var runServer = require('./lib/server');
 
 module.exports = function (commander) {
     var pkgurl = path.resolve('package.json');
@@ -36,9 +36,15 @@ module.exports = function (commander) {
     if (commander.watch) {
         return watch(commander, build);
     }
+    if (commander.stop) {
+        return runServer.stop();
+    }
     if (commander.server) {
-        server();
-        return watch(commander, build);
+        return runServer(commander, {
+            build: build,
+            server: require('ssr'),
+            watch: watch
+        });
     }
     if (commander.clean) {
         return clean(commander);

package/lib/build.js

@@ -144,15 +144,12 @@ function build(commander, changeFile) {
     var _path;
     var tocHTML = '';//单页面导航静态页面
     var navHTML = '';
-    var pathArr = file.readMDSync(todir + 'md/');
-
-
-    if (changeFile) pathArr = [changeFile];
+    var allPathArr = file.readMDSync(todir + 'md/');
 
     // 按文件名前面的数字排序
     // 如果文件名以数字开头（格式：数字.标题.md），按数字排序
     // 如果文件名不以数字开头，排在有序号的后面
-    pathArr.sort(function(a, b) {
+    allPathArr.sort(function(a, b) {
         var aBasename = path.basename(a, '.md');
         var bBasename = path.basename(b, '.md');
         
@@ -179,8 +176,22 @@ function build(commander, changeFile) {
         return aBasename.localeCompare(bBasename);
     });
 
+    // 增量编译时只写变更文件，但上一节/下一节、导航使用全量文件列表计算
+    var buildPathArr = allPathArr;
+    if (changeFile) {
+        var normalizedChangeFile = path.normalize(changeFile);
+        var matchedFile = null;
+        for (var c = 0; c < allPathArr.length; c++) {
+            if (path.normalize(allPathArr[c]) === normalizedChangeFile) {
+                matchedFile = allPathArr[c];
+                break;
+            }
+        }
+        buildPathArr = [matchedFile || normalizedChangeFile];
+    }
+
     // 先处理所有md文件，包括第一个md文件
-    pathArr.forEach(function (item, idx) {
+    buildPathArr.forEach(function (item) {
         //菜单层级
         var isIndex = false
         var len = item.replace(process.cwd() + '/md/', '').split('/').length;
@@ -195,7 +206,7 @@ function build(commander, changeFile) {
         var _path = path.normalize(process.cwd() + '/html/' + itemRel).replace('.md', ".html");
         
         //导航菜单生成 - 传入HTML路径作为当前页面
-        var navHTML = nav(zhangdocsmd, _path, pathArr, len);
+        var navHTML = nav(zhangdocsmd, _path, allPathArr, len);
 
         let mdContent = file.read(item);
         // 自动把 \[ ... \] 替换为 $$ ... $$
@@ -225,9 +236,17 @@ function build(commander, changeFile) {
         var prevTitle = null;
         var nextTitle = null;
         
-        if (idx > 0) {
+        var currentIndex = -1;
+        for (var i = 0; i < allPathArr.length; i++) {
+            if (path.normalize(allPathArr[i]) === path.normalize(item)) {
+                currentIndex = i;
+                break;
+            }
+        }
+
+        if (currentIndex > 0) {
             // 上一节
-            var prevItem = pathArr[idx - 1];
+            var prevItem = allPathArr[currentIndex - 1];
             var prevItemRel = path.normalize(prevItem);
             prevItemRel = prevItemRel.replace(path.normalize(process.cwd() + '/md/'), '');
             var prevPath = path.normalize(process.cwd() + '/html/' + prevItemRel).replace('.md', ".html");
@@ -247,9 +266,9 @@ function build(commander, changeFile) {
             prevTitle = path.basename(prevItem, '.md');
         }
         
-        if (idx < pathArr.length - 1) {
+        if (currentIndex > -1 && currentIndex < allPathArr.length - 1) {
             // 下一节
-            var nextItem = pathArr[idx + 1];
+            var nextItem = allPathArr[currentIndex + 1];
             var nextItemRel = path.normalize(nextItem);
             nextItemRel = nextItemRel.replace(path.normalize(process.cwd() + '/md/'), '');
             var nextPath = path.normalize(process.cwd() + '/html/' + nextItemRel).replace('.md', ".html");
@@ -291,8 +310,8 @@ function build(commander, changeFile) {
 
     // 单独生成index.html作为目录页面
     var indexPath = path.normalize(process.cwd() + '/index.html');
-    var indexNavHTML = nav(zhangdocsmd, indexPath, pathArr, 0);
-    var indexMarkedstr = generateIndexPage(zhangdocsmd, pathArr, indexPath, file.relativePath(indexPath, process.cwd()));
+    var indexNavHTML = nav(zhangdocsmd, indexPath, allPathArr, 0);
+    var indexMarkedstr = generateIndexPage(zhangdocsmd, allPathArr, indexPath, file.relativePath(indexPath, process.cwd()));
     
     html = file.ejs(template + '/layout.ejs', {
         title: pkg.name,//项目工程名字

package/lib/server-worker.js

@@ -0,0 +1,63 @@
+/**
+ * 后台服务模式子进程：启动静态服务 + 监听 md 变更
+ * 由 lib/server.js 以 detached 方式拉起，勿直接调用
+ */
+var fs = require('fs');
+var path = require('path');
+var file = require('./file');
+var build = require('./build');
+var watch = require('./watch');
+var server = require('ssr');
+
+var pidDir = path.join(process.cwd(), '.zhangdocs');
+var pidFile = path.join(pidDir, 'server.pid');
+var logFile = path.join(pidDir, 'server.log');
+
+function appendLog(line) {
+    try {
+        if (!fs.existsSync(pidDir)) {
+            file.mkdirsSync(pidDir, 0o777);
+        }
+        fs.appendFileSync(logFile, line + '\n', 'utf8');
+    } catch (e) {
+        // ignore
+    }
+}
+
+function cleanup() {
+    try {
+        if (fs.existsSync(pidFile)) {
+            fs.unlinkSync(pidFile);
+        }
+    } catch (e) {
+        // ignore
+    }
+}
+
+process.on('SIGINT', function () {
+    cleanup();
+    process.exit(0);
+});
+process.on('SIGTERM', function () {
+    cleanup();
+    process.exit(0);
+});
+process.on('exit', cleanup);
+
+try {
+    if (!fs.existsSync(pidDir)) {
+        file.mkdirsSync(pidDir, 0o777);
+    }
+    fs.writeFileSync(pidFile, String(process.pid), 'utf8');
+
+    var commanderStub = {};
+    build(commanderStub);
+    server();
+    watch(commanderStub, build);
+
+    appendLog('[' + new Date().toISOString() + '] doc server started (PID ' + process.pid + ')');
+} catch (err) {
+    appendLog('[' + new Date().toISOString() + '] doc server failed: ' + (err && err.stack ? err.stack : err));
+    cleanup();
+    process.exit(1);
+}

package/lib/server.js

@@ -0,0 +1,135 @@
+var fs = require('fs');
+var path = require('path');
+var spawn = require('child_process').spawn;
+var color = require('colors-cli');
+var file = require('./file');
+
+var PID_DIR = '.zhangdocs';
+var PID_NAME = 'server.pid';
+var LOG_NAME = 'server.log';
+
+function pidPath() {
+    return path.join(process.cwd(), PID_DIR, PID_NAME);
+}
+
+function logPath() {
+    return path.join(process.cwd(), PID_DIR, LOG_NAME);
+}
+
+function ensurePidDir() {
+    var dir = path.join(process.cwd(), PID_DIR);
+    if (!fs.existsSync(dir)) {
+        file.mkdirsSync(dir, 0o777);
+    }
+    return dir;
+}
+
+function isProcessAlive(pid) {
+    if (!pid || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+function readPid() {
+    var file = pidPath();
+    if (!fs.existsSync(file)) {
+        return null;
+    }
+    var pid = parseInt(String(fs.readFileSync(file, 'utf8')).trim(), 10);
+    return isNaN(pid) ? null : pid;
+}
+
+function clearPidFile() {
+    try {
+        if (fs.existsSync(pidPath())) {
+            fs.unlinkSync(pidPath());
+        }
+    } catch (e) {
+        // ignore
+    }
+}
+
+function killPid(pid) {
+    if (process.platform === 'win32') {
+        spawn('taskkill', ['/PID', String(pid), '/T', '/F'], {
+            stdio: 'ignore',
+            windowsHide: true
+        });
+    } else {
+        process.kill(pid, 'SIGTERM');
+    }
+}
+
+function stopBackground() {
+    var pid = readPid();
+    if (!pid || !isProcessAlive(pid)) {
+        clearPidFile();
+        console.log(color.yellow('\n 未发现运行中的后台 doc server。\n'));
+        return;
+    }
+    killPid(pid);
+    clearPidFile();
+    console.log(color.green('\n 已停止后台 doc server (PID ' + pid + ')。\n'));
+}
+
+function startForeground(commander, build, server, watch) {
+    build(commander);
+    server();
+    watch(commander, build);
+}
+
+function startDaemon(commander, build) {
+    var pid = readPid();
+    if (pid && isProcessAlive(pid)) {
+        console.log(color.yellow('\n doc server 已在后台运行 (PID ' + pid + ')。'));
+        console.log(' 日志: ' + logPath());
+        console.log(' 停止: doc -s --stop\n');
+        return;
+    }
+    if (pid) {
+        clearPidFile();
+    }
+
+    ensurePidDir();
+    build(commander);
+
+    var worker = path.join(__dirname, 'server-worker.js');
+    var child = spawn(process.execPath, [worker], {
+        cwd: process.cwd(),
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env: process.env
+    });
+
+    child.unref();
+
+    console.log(color.green('\n doc server 已在后台启动。'));
+    console.log(' 可关闭当前命令行窗口，服务会继续运行。');
+    console.log(' 日志: ' + logPath());
+    console.log(' 停止: doc -s --stop\n');
+}
+
+/**
+ * @param {object} commander
+ * @param {{ build: Function, server: Function, watch: Function }} deps
+ */
+function runServer(commander, deps) {
+    if (commander.stop) {
+        return stopBackground();
+    }
+    if (commander.daemon) {
+        return startDaemon(commander, deps.build);
+    }
+    return startForeground(commander, deps.build, deps.server, deps.watch);
+}
+
+runServer.stop = stopBackground;
+
+module.exports = runServer;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zhangdocs",
-    "version": "1.1.31",
+    "version": "1.1.34",
     "description": "Simple document generation tool. Dependence Node.js run.",
     "repository": {
         "type": "git",

package/theme/handbook/gitignore

@@ -20,3 +20,4 @@ Thumbs.db
 node_modules
 .cache
 zhangdocs-theme-*/
+.zhangdocs/

package/theme/handbook/head.ejs

@@ -34,13 +34,23 @@
       mermaid.initialize({
         startOnLoad: true,
         theme: 'default',
+        flowchart: {
+          useMaxWidth: true,
+          htmlLabels: false,
+          wrappingWidth: 180,
+          nodeSpacing: 45,
+          rankSpacing: 50,
+          padding: 16
+        },
+        themeCSS: '.mermaid .label text, .mermaid .nodeLabel { dominant-baseline: central; }',
         themeVariables: {
           primaryColor: '#ff6b6b',
           primaryTextColor: '#333',
           primaryBorderColor: '#ff6b6b',
           lineColor: '#333',
           secondaryColor: '#f8f9fa',
-          tertiaryColor: '#fff'
+          tertiaryColor: '#fff',
+          fontSize: '10px'
         }
       });
     });

package/theme/handbook/layout.ejs

@@ -103,6 +103,104 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
           
           // 标记为已初始化
           isInitialized = true;
+
+          function getDirectLink(li) {
+            if (!li || !li.children) {
+              return null;
+            }
+            for (var i = 0; i < li.children.length; i++) {
+              if (li.children[i].tagName === 'A') {
+                return li.children[i];
+              }
+            }
+            return li.querySelector('a');
+          }
+
+          function getDecodedTail(input) {
+            var tail = '';
+            try {
+              var parsed = new URL(input, window.location.origin);
+              tail = (parsed.pathname || '').split('/').pop() || '';
+            } catch (e) {
+              tail = String(input || '')
+                .split('#')[0]
+                .split('?')[0]
+                .split('/')
+                .pop() || '';
+            }
+            try {
+              return decodeURIComponent(tail);
+            } catch (e2) {
+              return tail;
+            }
+          }
+
+          function stripExt(name) {
+            return String(name || '').replace(/\.(html|md)$/i, '');
+          }
+
+          // 打开菜单时定位到当前页面，并高亮其父级目录路径
+          function locateCurrentMenuItem() {
+            var menuContent = menuPopup.querySelector('.menu-popup-content');
+            if (!menuContent) {
+              return;
+            }
+
+            var previousMarks = menuContent.querySelectorAll(
+              '.menu-current-item, .menu-current-link, .menu-ancestor-item'
+            );
+            previousMarks.forEach(function(node) {
+              node.classList.remove('menu-current-item');
+              node.classList.remove('menu-current-link');
+              node.classList.remove('menu-ancestor-item');
+            });
+
+            var currentLi = menuContent.querySelector('li.active');
+            if (!currentLi) {
+              // 回退：按当前 URL 匹配菜单项（兼容中文路径编码）
+              var currentTail = getDecodedTail(window.location.href);
+              var currentBase = stripExt(currentTail);
+              if (currentTail) {
+                var links = menuContent.querySelectorAll('a[href]');
+                for (var i = 0; i < links.length; i++) {
+                  var linkTail = getDecodedTail(links[i].getAttribute('href'));
+                  var linkBase = stripExt(linkTail);
+                  if (linkTail === currentTail || linkBase === currentBase) {
+                    currentLi = links[i].closest('li');
+                    break;
+                  }
+                }
+              }
+            }
+
+            if (!currentLi) {
+              return;
+            }
+
+            currentLi.classList.add('menu-current-item');
+            var currentLink = getDirectLink(currentLi);
+            if (currentLink) {
+              currentLink.classList.add('menu-current-link');
+            }
+
+            var parent = currentLi.parentElement;
+            while (parent && parent !== menuPopup) {
+              if (parent.tagName === 'LI') {
+                parent.classList.add('menu-ancestor-item');
+              }
+              parent = parent.parentElement;
+            }
+
+            try {
+              currentLi.scrollIntoView({
+                block: 'center',
+                inline: 'nearest'
+              });
+            } catch (e) {
+              // 兼容旧浏览器
+              currentLi.scrollIntoView();
+            }
+          }
           
           // 打开菜单
           function openMenu() {
@@ -110,6 +208,7 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
             menuPopup.classList.add('menu-popup-show');
             menuOverlay.classList.add('menu-overlay-show');
             document.body.style.overflow = 'hidden'; // 防止背景滚动
+            setTimeout(locateCurrentMenuItem, 50);
           }
           
           // 关闭菜单
@@ -404,9 +503,277 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
     setTimeout(initMenuPopup, 500);
     setTimeout(initMenuPopup, 1000);
     
-    // 图片预览功能初始化
+    // 图片/mermaid 预览功能初始化
     (function() {
       var imageViewer = null;
+      var imageViewerObserver = null;
+      var viewerRefreshTimer = null;
+      var mermaidPreviewModal = null;
+      var mermaidPreviewScale = 1;
+      var mermaidPreviewOffsetX = 0;
+      var mermaidPreviewOffsetY = 0;
+
+      function applyMermaidPreviewTransform(container) {
+        if (!container) {
+          return;
+        }
+        container.style.transform =
+          'translate(' + mermaidPreviewOffsetX + 'px, ' + mermaidPreviewOffsetY + 'px) scale(' + mermaidPreviewScale + ')';
+      }
+
+      function scheduleInitImageViewer(delay) {
+        if (viewerRefreshTimer) {
+          clearTimeout(viewerRefreshTimer);
+        }
+        viewerRefreshTimer = setTimeout(function() {
+          initImageViewer();
+        }, typeof delay === 'number' ? delay : 80);
+      }
+
+      function ensureMermaidPreviewModal() {
+        if (mermaidPreviewModal) {
+          return mermaidPreviewModal;
+        }
+        var modal = document.createElement('div');
+        modal.id = 'mermaid-preview-modal';
+        modal.style.cssText = [
+          'position:fixed',
+          'inset:0',
+          'display:none',
+          'z-index:100010',
+          'background:rgba(12,16,22,0.82)',
+          'align-items:center',
+          'justify-content:center',
+          'padding:24px'
+        ].join(';');
+
+        var container = document.createElement('div');
+        container.className = 'mermaid-preview-container';
+        container.style.cssText = [
+          'position:relative',
+          'max-width:96vw',
+          'max-height:92vh',
+          'overflow:hidden',
+          'background:#fff',
+          'border-radius:10px',
+          'padding:14px',
+          'box-shadow:0 12px 36px rgba(0,0,0,0.35)',
+          'transform-origin:center center',
+          'transition:transform 0.08s linear'
+        ].join(';');
+
+        var closeBtn = document.createElement('button');
+        closeBtn.type = 'button';
+        closeBtn.innerHTML = '&times;';
+        closeBtn.setAttribute('aria-label', '关闭Mermaid预览');
+        closeBtn.style.cssText = [
+          'position:absolute',
+          'right:10px',
+          'top:6px',
+          'width:28px',
+          'height:28px',
+          'border:none',
+          'border-radius:50%',
+          'background:rgba(0,0,0,0.08)',
+          'cursor:pointer',
+          'font-size:20px',
+          'line-height:1'
+        ].join(';');
+
+        var content = document.createElement('div');
+        content.className = 'mermaid-preview-content';
+        content.style.cssText = [
+          'min-width:320px',
+          'min-height:160px',
+          'width:90vw',
+          'height:82vh',
+          'display:flex',
+          'align-items:center',
+          'justify-content:center',
+          'overflow:hidden',
+          'cursor:default'
+        ].join(';');
+
+        closeBtn.addEventListener('click', function() {
+          modal.style.display = 'none';
+          document.body.style.overflow = '';
+          mermaidPreviewScale = 1;
+          mermaidPreviewOffsetX = 0;
+          mermaidPreviewOffsetY = 0;
+          applyMermaidPreviewTransform(container);
+        });
+        modal.addEventListener('click', function(e) {
+          if (e.target === modal) {
+            modal.style.display = 'none';
+            document.body.style.overflow = '';
+            mermaidPreviewScale = 1;
+            mermaidPreviewOffsetX = 0;
+            mermaidPreviewOffsetY = 0;
+            applyMermaidPreviewTransform(container);
+          }
+        });
+        document.addEventListener('keydown', function(e) {
+          if (e.key === 'Escape' && modal.style.display !== 'none') {
+            modal.style.display = 'none';
+            document.body.style.overflow = '';
+            mermaidPreviewScale = 1;
+            mermaidPreviewOffsetX = 0;
+            mermaidPreviewOffsetY = 0;
+            applyMermaidPreviewTransform(container);
+          }
+        });
+
+        container.appendChild(closeBtn);
+        container.appendChild(content);
+        modal.appendChild(container);
+        document.body.appendChild(modal);
+        mermaidPreviewModal = modal;
+        return mermaidPreviewModal;
+      }
+
+      function bindMermaidPreview(markdownBody) {
+        var mermaidSvgs = markdownBody.querySelectorAll('.mermaid svg');
+        mermaidSvgs.forEach(function(svg) {
+          if (svg.getAttribute('data-mermaid-preview-bound') === 'true') {
+            return;
+          }
+          svg.setAttribute('data-mermaid-preview-bound', 'true');
+          svg.style.cursor = 'zoom-in';
+          svg.addEventListener('click', function(e) {
+            e.preventDefault();
+            e.stopPropagation();
+
+            var modal = ensureMermaidPreviewModal();
+            var content = modal.querySelector('.mermaid-preview-content');
+            var container = modal.querySelector('.mermaid-preview-container');
+            if (!content || !container) {
+              return;
+            }
+            content.innerHTML = '';
+
+            var clone = svg.cloneNode(true);
+            var vb = clone.getAttribute('viewBox');
+            var vbWidth = 0;
+            var vbHeight = 0;
+            if (vb) {
+              var parts = vb.trim().split(/\s+/);
+              if (parts.length === 4) {
+                vbWidth = parseFloat(parts[2]) || 0;
+                vbHeight = parseFloat(parts[3]) || 0;
+              }
+            }
+            if (!vbWidth || !vbHeight) {
+              var rect = svg.getBoundingClientRect();
+              vbWidth = rect.width || 800;
+              vbHeight = rect.height || 500;
+            }
+
+            var maxWidth = Math.floor(window.innerWidth * 0.9);
+            var maxHeight = Math.floor(window.innerHeight * 0.82);
+            var fitScale = Math.min(maxWidth / vbWidth, maxHeight / vbHeight);
+            if (!isFinite(fitScale) || fitScale <= 0) {
+              fitScale = 1;
+            }
+            // 预览默认尽量放大显示，但保留比例，避免文字过小
+            var defaultScale = Math.max(fitScale, 1.25);
+            var renderWidth = Math.round(vbWidth * defaultScale);
+            var renderHeight = Math.round(vbHeight * defaultScale);
+            if (renderWidth > maxWidth || renderHeight > maxHeight) {
+              var clampScale = Math.min(maxWidth / vbWidth, maxHeight / vbHeight);
+              renderWidth = Math.round(vbWidth * clampScale);
+              renderHeight = Math.round(vbHeight * clampScale);
+            }
+
+            clone.removeAttribute('width');
+            clone.removeAttribute('height');
+            clone.style.width = Math.max(320, renderWidth) + 'px';
+            clone.style.height = 'auto';
+            clone.style.maxWidth = '100%';
+            clone.style.maxHeight = '100%';
+            clone.style.display = 'block';
+            clone.style.cursor = 'grab';
+            clone.style.userSelect = 'none';
+            content.appendChild(clone);
+
+            // 改为缩放整个预览容器，不出现滚动条
+            if (content.__wheelZoomHandler) {
+              content.removeEventListener('wheel', content.__wheelZoomHandler, false);
+            }
+            var wheelZoomHandler = function(evt) {
+              evt.preventDefault();
+              var zoomStep = evt.deltaY < 0 ? 1.08 : 0.92;
+              mermaidPreviewScale = Math.max(0.8, Math.min(2.2, mermaidPreviewScale * zoomStep));
+              applyMermaidPreviewTransform(container);
+            };
+            content.addEventListener('wheel', wheelZoomHandler, { passive: false });
+            content.__wheelZoomHandler = wheelZoomHandler;
+
+            // 支持按住左键拖动（小手光标）
+            content.style.cursor = 'grab';
+            var isDragging = false;
+            var dragStartX = 0;
+            var dragStartY = 0;
+            var dragBaseX = 0;
+            var dragBaseY = 0;
+
+            if (content.__dragMouseDownHandler) {
+              content.removeEventListener('mousedown', content.__dragMouseDownHandler, false);
+            }
+            if (content.__dragMouseMoveHandler) {
+              window.removeEventListener('mousemove', content.__dragMouseMoveHandler, false);
+            }
+            if (content.__dragMouseUpHandler) {
+              window.removeEventListener('mouseup', content.__dragMouseUpHandler, false);
+            }
+
+            var dragMouseDownHandler = function(evt) {
+              if (evt.button !== 0) {
+                return;
+              }
+              isDragging = true;
+              dragStartX = evt.clientX;
+              dragStartY = evt.clientY;
+              dragBaseX = mermaidPreviewOffsetX;
+              dragBaseY = mermaidPreviewOffsetY;
+              content.style.cursor = 'grabbing';
+              clone.style.cursor = 'grabbing';
+              container.style.transition = 'none';
+              evt.preventDefault();
+            };
+            var dragMouseMoveHandler = function(evt) {
+              if (!isDragging) {
+                return;
+              }
+              mermaidPreviewOffsetX = dragBaseX + (evt.clientX - dragStartX);
+              mermaidPreviewOffsetY = dragBaseY + (evt.clientY - dragStartY);
+              applyMermaidPreviewTransform(container);
+            };
+            var dragMouseUpHandler = function() {
+              if (!isDragging) {
+                return;
+              }
+              isDragging = false;
+              content.style.cursor = 'grab';
+              clone.style.cursor = 'grab';
+              container.style.transition = 'transform 0.08s linear';
+            };
+
+            content.addEventListener('mousedown', dragMouseDownHandler, false);
+            window.addEventListener('mousemove', dragMouseMoveHandler, false);
+            window.addEventListener('mouseup', dragMouseUpHandler, false);
+            content.__dragMouseDownHandler = dragMouseDownHandler;
+            content.__dragMouseMoveHandler = dragMouseMoveHandler;
+            content.__dragMouseUpHandler = dragMouseUpHandler;
+
+            modal.style.display = 'flex';
+            document.body.style.overflow = 'hidden';
+            mermaidPreviewScale = 1;
+            mermaidPreviewOffsetX = 0;
+            mermaidPreviewOffsetY = 0;
+            applyMermaidPreviewTransform(container);
+          });
+        });
+      }
       
       function initImageViewer() {
         // 查找markdown-body容器
@@ -414,6 +781,20 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
         if (!markdownBody) {
           return;
         }
+
+        // 监听内容变化：mermaid 常常是异步渲染 SVG
+        if (!imageViewerObserver) {
+          imageViewerObserver = new MutationObserver(function() {
+            scheduleInitImageViewer(80);
+          });
+          imageViewerObserver.observe(markdownBody, {
+            childList: true,
+            subtree: true
+          });
+        }
+
+        // Mermaid 保持原始 SVG 渲染，点击时弹出预览（避免转图片导致文字裁切）
+        bindMermaidPreview(markdownBody);
         
         // 查找所有图片
         var images = markdownBody.querySelectorAll('img');
@@ -433,7 +814,7 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
         // 为图片添加样式和点击事件
         images.forEach(function(img) {
           // 跳过已经是链接内的图片
-          if (img.parentElement.tagName === 'A') {
+          if (img.parentElement && img.parentElement.tagName === 'A') {
             return;
           }
           
@@ -446,11 +827,41 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
         try {
           imageViewer = new Viewer(markdownBody, {
             inline: false,
-            viewed: function() {
-              // 查看图片时的回调
-            },
-            hidden: function() {
-              // 关闭查看器时的回调
+            viewed: function(event) {
+              // 仅对 Mermaid 图应用更大的默认缩放和白底，提升文字可读性
+              try {
+                var originalImage = event && event.detail && event.detail.originalImage;
+                var isMermaidImage = !!(
+                  originalImage &&
+                  originalImage.classList &&
+                  originalImage.classList.contains('mermaid-preview-image')
+                );
+                if (!isMermaidImage || !imageViewer) {
+                  return;
+                }
+
+                var imageData = imageViewer.imageData;
+                var viewerData = imageViewer.viewerData;
+                if (!imageData || !viewerData || !imageData.naturalWidth || !imageData.naturalHeight) {
+                  return;
+                }
+
+                var fitRatio = Math.min(
+                  viewerData.width / imageData.naturalWidth,
+                  viewerData.height / imageData.naturalHeight
+                );
+                var targetRatio = Math.max(fitRatio * 1.2, 1.25);
+                imageViewer.zoomTo(targetRatio);
+
+                if (imageViewer.image) {
+                  imageViewer.image.style.backgroundColor = '#ffffff';
+                  imageViewer.image.style.padding = '14px';
+                  imageViewer.image.style.borderRadius = '8px';
+                  imageViewer.image.style.boxShadow = '0 6px 24px rgba(0, 0, 0, 0.25)';
+                }
+              } catch (e) {
+                console.error('Mermaid 预览缩放初始化失败:', e);
+              }
             },
             toolbar: {
               zoomIn: true,
@@ -484,6 +895,8 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
       // 延迟初始化（处理动态显示的情况）
       setTimeout(initImageViewer, 500);
       setTimeout(initImageViewer, 1000);
+      setTimeout(initImageViewer, 2000);
+      setTimeout(initImageViewer, 3500);
     })();
     
     // 上一节/下一节导航功能

package/theme/handbook/source/css/_partial/markdown.styl

@@ -30,6 +30,25 @@
             cursor: zoom-in
             &:hover
                 opacity: 0.9
+        &.mermaid-preview-image
+            background: #fff
+            padding: 10px
+            border: 1px solid #e5e7eb
+            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.08)
+    .mermaid
+        display: flex
+        justify-content: center
+        overflow-x: auto
+        overflow-y: hidden
+        padding: 8px 0
+        background: #fff
+        border-radius: 6px
+
+        svg
+            width: 130% !important
+            height: auto !important
+            min-width: 1100px
+            max-width: none !important
     a
         color: #0969da
         text-decoration: none

package/theme/handbook/source/css/main.styl

@@ -167,6 +167,17 @@ $hover-color = #1ABC9C         // 悬停绿色
                         background: rgba($primary-color, 0.1)
                         color: $primary-color
                         font-weight: 600
+                &.menu-ancestor-item
+                    > a
+                        background: rgba($primary-color, 0.06)
+                        color: darken($primary-color, 10%)
+                &.menu-current-item
+                    > a,
+                    > a.menu-current-link
+                        background: rgba($primary-color, 0.14)
+                        color: $primary-color
+                        font-weight: 700
+                        border-left: 3px solid $primary-color
                 ul
                     margin-left: 20px
                     margin-top: 5px