zhangdocs 1.1.29 → 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

@@ -32,6 +32,8 @@ npm install -g zhangdocs
 npm install zhangdocs
 ```
 
+安装完成后，可以使用 `doc` 命令来操作项目。
+
 ## 🚀 快速开始
 
 ### 1. 初始化项目
@@ -39,13 +41,13 @@ npm install zhangdocs
 在项目目录下运行：
 
 ```bash
-zhangdocs init
+doc init
 ```
 
 或者指定项目名称：
 
 ```bash
-zhangdocs init --Create my-docs
+doc init --Create my-docs
 ```
 
 初始化过程会引导你配置项目信息，包括：
@@ -75,7 +77,7 @@ zhangdocs init --Create my-docs
 ### 3. 构建文档
 
 ```bash
-zhangdocs build
+doc build
 ```
 
 构建完成后，HTML 文件将生成在 `html/` 目录下，首页 `index.html` 会生成在项目根目录。
@@ -83,15 +85,29 @@ zhangdocs build
 ### 4. 启动开发服务器
 
 ```bash
-zhangdocs server
+doc -s
 ```
 
 这将启动一个本地服务器，并监听文件变化自动重新构建。
 
+后台运行（关闭命令行窗口后服务仍继续）：
+
+```bash
+doc -s -d
+```
+
+停止后台服务：
+
+```bash
+doc -s --stop
+```
+
+日志文件位于项目目录下的 `.zhangdocs/server.log`。
+
 ### 5. 监听文件变化
 
 ```bash
-zhangdocs watch
+doc watch
 ```
 
 监听 `md/` 目录下的文件变化，自动重新构建。
@@ -100,14 +116,16 @@ zhangdocs watch
 
 | 命令 | 说明 |
 |------|------|
-| `zhangdocs init` | 初始化项目 |
-| `zhangdocs build` | 构建静态页面 |
-| `zhangdocs watch` | 监听文件变化并自动构建 |
-| `zhangdocs server` | 启动开发服务器（包含 watch 功能） |
-| `zhangdocs clean` | 清理构建文件 |
-| `zhangdocs deploy` | 部署文档 |
-| `zhangdocs theme` | 主题管理 |
-| `zhangdocs -V` | 查看版本号 |
+| `doc init` | 初始化项目 |
+| `doc build` | 构建静态页面 |
+| `doc watch` | 监听文件变化并自动构建 |
+| `doc -s` | 启动开发服务器（包含 watch 功能） |
+| `doc -s -d` | 后台启动开发服务器，可关闭终端 |
+| `doc -s --stop` | 停止后台开发服务器 |
+| `doc clean` | 清理构建文件 |
+| `doc --deploy` | 部署文档 |
+| `doc theme` | 主题管理 |
+| `doc -V` | 查看版本号 |
 
 ## ⚙️ 配置说明
 
@@ -210,7 +228,7 @@ $$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
 
 1. 修改现有主题的样式和模板
 2. 创建新主题
-3. 使用 `zhangdocs theme` 命令管理主题
+3. 使用 `doc theme` 命令管理主题
 
 ## 📝 注意事项
 
@@ -218,19 +236,3 @@ $$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
 2. **图片路径**：图片应放在 `static/img/` 目录下，在 Markdown 中使用相对路径引用
 3. **数学公式**：使用 `$...$` 表示行内公式，`$$...$$` 表示块级公式
 4. **Mermaid 图表**：在代码块中指定语言为 `mermaid`，工具会自动处理特殊字符转义
-
-## 📄 许可证
-
-MIT License
-
-## 👤 作者
-
-kenny wang <wowohoo@qq.com>
-
-## 🔗 相关链接
-
-- [GitHub 仓库](https://github.com/zhangrenyang/zhangdocs.git)
-
----
-
-**Happy Documenting! 📚**

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.29",
+    "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'
         }
       });
     });