zhangdocs 1.1.26 → 1.1.28

package/README.md

@@ -1,40 +1,236 @@
-# 测试文档
+# zhangdocs
 
-这是一个测试文档，用于验证 highlight.js 是否正常工作。
+一个简单易用的文档生成工具，可以将 Markdown 文件编译成美观的 HTML 静态文档网站。
 
-## JavaScript 代码示例
+## ✨ 功能特性
 
-```js
-function hello() {
-    console.log("Hello, World!");
-    return "success";
-}
+- 📝 **Markdown 支持** - 完整的 Markdown 语法支持，包括 GFM（GitHub Flavored Markdown）
+- 🎨 **代码高亮** - 基于 highlight.js 的代码语法高亮，支持多种编程语言
+- 📊 **Mermaid 图表** - 支持流程图、类图、时序图等多种图表类型
+- 🔢 **数学公式** - 支持 LaTeX 数学公式渲染（行内和块级）
+- 📑 **自动目录** - 自动生成页面目录导航和全局导航菜单
+- 🔄 **章节导航** - 支持上一节/下一节按钮和键盘快捷键（`Ctrl + ←/→`）
+- 🏠 **目录首页** - 自动生成文档目录索引页面
+- 🎯 **文件排序** - 支持按文件名前缀数字自动排序章节
+- 🔒 **访问控制** - 支持 Token 验证保护文档内容
+- 🖼️ **图片预览** - 集成 Viewer.js 支持图片点击预览
+- 👀 **实时预览** - 支持文件监听和自动重新构建
+- 🎨 **主题定制** - 支持自定义主题和样式
+- 📱 **响应式设计** - 适配桌面和移动设备
+
+## 📦 安装
+
+### 全局安装
+
+```bash
+npm install -g zhangdocs
+```
+
+### 本地安装
+
+```bash
+npm install zhangdocs
+```
+
+## 🚀 快速开始
+
+### 1. 初始化项目
+
+在项目目录下运行：
+
+```bash
+zhangdocs init
+```
+
+或者指定项目名称：
+
+```bash
+zhangdocs init --Create my-docs
+```
+
+初始化过程会引导你配置项目信息，包括：
+- 项目名称
+- 版本号
+- 描述
+- 关键词
+- 许可证
+- 主题选择
+
+### 2. 编写文档
+
+在 `md/` 目录下创建 Markdown 文件，例如：
+
+```markdown
+# 第一章 介绍
+
+这是第一章的内容。
+
+## 1.1 概述
+
+概述内容...
+```
+
+**文件命名建议**：使用 `数字.标题.md` 格式（如 `1.介绍.md`），工具会自动按数字排序。
+
+### 3. 构建文档
+
+```bash
+zhangdocs build
 ```
 
-## JSON 代码示例
+构建完成后，HTML 文件将生成在 `html/` 目录下，首页 `index.html` 会生成在项目根目录。
+
+### 4. 启动开发服务器
+
+```bash
+zhangdocs server
+```
+
+这将启动一个本地服务器，并监听文件变化自动重新构建。
+
+### 5. 监听文件变化
+
+```bash
+zhangdocs watch
+```
+
+监听 `md/` 目录下的文件变化，自动重新构建。
+
+## 📖 命令说明
+
+| 命令 | 说明 |
+|------|------|
+| `zhangdocs init` | 初始化项目 |
+| `zhangdocs build` | 构建静态页面 |
+| `zhangdocs watch` | 监听文件变化并自动构建 |
+| `zhangdocs server` | 启动开发服务器（包含 watch 功能） |
+| `zhangdocs clean` | 清理构建文件 |
+| `zhangdocs deploy` | 部署文档 |
+| `zhangdocs theme` | 主题管理 |
+| `zhangdocs -V` | 查看版本号 |
+
+## ⚙️ 配置说明
+
+项目配置在 `package.json` 的 `zhangdocs` 字段中：
 
 ```json
 {
-    "name": "test",
-    "version": "1.0.0",
-    "dependencies": {
-        "highlight.js": "^11.11.1"
-    }
+  "zhangdocs": {
+    "theme": "handbook",
+    "md": [
+      "README.md"
+    ]
+  }
 }
 ```
 
-## Diff 代码示例
+- `theme`: 使用的主题名称（位于 `theme/` 目录下）
+- `md`: 文档入口文件列表（相对于 `md/` 目录）
 
-```diff
-+ 这是新增的行
-- 这是删除的行
-  这是未修改的行
+## 📁 项目结构
+
+```
+项目根目录/
+├── md/                    # Markdown 源文件目录
+│   ├── README.md
+│   └── ...
+├── html/                  # 生成的 HTML 文件目录
+│   └── ...
+├── static/                # 静态资源目录（CSS、图片等）
+│   ├── css/
+│   └── img/
+├── theme/                 # 主题目录
+│   └── handbook/
+│       ├── layout.ejs     # 布局模板
+│       ├── header.ejs     # 头部模板
+│       ├── footer.ejs     # 底部模板
+│       └── source/        # 主题源文件
+├── index.html             # 生成的目录首页
+└── package.json           # 项目配置
 ```
 
-## 数学公式
+## 🎯 主要功能
+
+### 代码高亮
+
+支持多种编程语言的代码高亮：
+
+````markdown
+```javascript
+function hello() {
+    console.log("Hello, World!");
+}
+```
+````
+
+### Mermaid 图表
+
+支持多种图表类型：
+
+````markdown
+```mermaid
+graph TD
+    A[开始] --> B{判断}
+    B -->|是| C[执行]
+    B -->|否| D[结束]
+```
+````
+
+### 数学公式
+
+支持行内公式和块级公式：
+
+```markdown
+行内公式：$E = mc^2$
+
+块级公式：
+$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
+```
+
+### 章节导航
+
+- 每个页面底部有"上一节"和"下一节"按钮
+- 支持键盘快捷键：
+  - `Ctrl + ←`：上一节
+  - `Ctrl + →`：下一节
+
+### 文件排序
+
+工具会自动按文件名前缀的数字排序：
+- `1.介绍.md` → `2.使用.md` → `3.API.md`
+- 没有数字前缀的文件会排在有序号文件的后面
+
+## 🔒 访问控制
+
+文档支持 Token 验证功能，可以在模板中配置访问令牌验证逻辑，保护文档内容不被未授权访问。
+
+## 🎨 主题定制
+
+项目支持自定义主题，主题文件位于 `theme/` 目录下。你可以：
+
+1. 修改现有主题的样式和模板
+2. 创建新主题
+3. 使用 `zhangdocs theme` 命令管理主题
+
+## 📝 注意事项
+
+1. **文件命名**：建议使用 `数字.标题.md` 格式，便于自动排序
+2. **图片路径**：图片应放在 `static/img/` 目录下，在 Markdown 中使用相对路径引用
+3. **数学公式**：使用 `$...$` 表示行内公式，`$$...$$` 表示块级公式
+4. **Mermaid 图表**：在代码块中指定语言为 `mermaid`，工具会自动处理特殊字符转义
+
+## 📄 许可证
+
+MIT License
+
+## 👤 作者
+
+kenny wang <wowohoo@qq.com>
+
+## 🔗 相关链接
 
-这是一个行内公式：$E = mc^2$
+- [GitHub 仓库](https://github.com/zhangrenyang/zhangdocs.git)
 
-这是一个块级公式：
+---
 
-$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
+**Happy Documenting! 📚**

package/index.html

@@ -71,7 +71,7 @@
         </div>
 
         
-            <div class="forkgithub"><a target="_blank" href="https://github.com/jaywcjlove/zhangdocs.git">fork on github</a></div>
+            <div class="forkgithub"><a target="_blank" href="https://github.com/zhangrenyang/zhangdocs.git">fork on github</a></div>
             
 
                 <section class="zhangdocs_nav_btn">
@@ -123,7 +123,7 @@
 <p>&#x8FD9;&#x662F;&#x4E00;&#x4E2A;&#x5757;&#x7EA7;&#x516C;&#x5F0F;&#xFF1A;</p>
 <p>$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$</p>
 
-                <div class="copyright">Powered by <a href="https://github.com/jaywcjlove/zhangdocs"
+                <div class="copyright">Powered by <a href="https://github.com/zhangrenyang/zhangdocs"
                         target="_blank">zhangdocs</a>. Dependence <a href="https://nodejs.org">Node.js</a> run.</div>
         </div>
 

package/lib/build.js

@@ -149,6 +149,36 @@ function build(commander, changeFile) {
 
     if (changeFile) pathArr = [changeFile];
 
+    // 按文件名前面的数字排序
+    // 如果文件名以数字开头（格式：数字.标题.md），按数字排序
+    // 如果文件名不以数字开头，排在有序号的后面
+    pathArr.sort(function(a, b) {
+        var aBasename = path.basename(a, '.md');
+        var bBasename = path.basename(b, '.md');
+        
+        // 提取文件名开头的数字
+        var aMatch = aBasename.match(/^(\d+)/);
+        var bMatch = bBasename.match(/^(\d+)/);
+        
+        var aNum = aMatch ? parseInt(aMatch[1], 10) : null;
+        var bNum = bMatch ? parseInt(bMatch[1], 10) : null;
+        
+        // 如果两个都有数字，按数字排序
+        if (aNum !== null && bNum !== null) {
+            return aNum - bNum;
+        }
+        // 如果只有a有数字，a排在前面
+        if (aNum !== null && bNum === null) {
+            return -1;
+        }
+        // 如果只有b有数字，b排在前面
+        if (aNum === null && bNum !== null) {
+            return 1;
+        }
+        // 如果两个都没有数字，保持原顺序（或按文件名排序）
+        return aBasename.localeCompare(bBasename);
+    });
+
     // 先处理所有md文件，包括第一个md文件
     pathArr.forEach(function (item, idx) {
         //菜单层级

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "zhangdocs",
-    "version": "1.1.26",
+    "version": "1.1.28",
     "description": "Simple document generation tool. Dependence Node.js run.",
     "repository": {
         "type": "git",
-        "url": "https://github.com/jaywcjlove/zhangdocs.git"
+        "url": "https://github.com/zhangrenyang/zhangdocs.git"
     },
     "main": "index.js",
     "bin": {

package/theme/handbook/layout.ejs

@@ -52,6 +52,13 @@
     </div>
   </div>
 
+  <!-- 滚动到底部按钮 -->
+  <button class="scroll-to-bottom" id="scroll-to-bottom" aria-label="滚动到底部" title="滚动到底部">
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M6 9l6 6 6-6"></path>
+    </svg>
+  </button>
+
   <!-- Token输入弹窗 -->
   <div id="token-modal"
 style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0,0,0,0.8); z-index: 9999; display: none; justify-content: center; align-items: center;">
@@ -449,5 +456,68 @@ style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background:
         }
       });
     })();
+    
+    // 滚动到底部功能
+    (function() {
+      var scrollToBottomBtn = document.getElementById('scroll-to-bottom');
+      if (!scrollToBottomBtn) {
+        return;
+      }
+      
+      // 检查是否在页面底部
+      function isAtBottom() {
+        var scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+        var scrollHeight = document.documentElement.scrollHeight;
+        var clientHeight = document.documentElement.clientHeight;
+        // 允许5px的误差
+        return scrollHeight - scrollTop - clientHeight <= 5;
+      }
+      
+      // 显示/隐藏按钮
+      function toggleButton() {
+        if (isAtBottom()) {
+          scrollToBottomBtn.classList.remove('show');
+        } else {
+          scrollToBottomBtn.classList.add('show');
+        }
+      }
+      
+      // 滚动到底部
+      function scrollToBottom() {
+        window.scrollTo({
+          top: document.documentElement.scrollHeight,
+          behavior: 'smooth'
+        });
+      }
+      
+      // 绑定点击事件
+      scrollToBottomBtn.addEventListener('click', function(e) {
+        e.preventDefault();
+        scrollToBottom();
+      });
+      
+      // 监听滚动事件
+      var scrollTimer = null;
+      window.addEventListener('scroll', function() {
+        // 使用节流，减少频繁检查
+        if (scrollTimer) {
+          clearTimeout(scrollTimer);
+        }
+        scrollTimer = setTimeout(toggleButton, 100);
+      }, { passive: true });
+      
+      // 初始检查
+      setTimeout(toggleButton, 500);
+      
+      // 监听内容变化（处理动态加载的内容）
+      var observer = new MutationObserver(function() {
+        setTimeout(toggleButton, 100);
+      });
+      
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true
+      });
+    })();
   </script>
   <% include footer.ejs %>

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

@@ -512,4 +512,53 @@ table
         
         .nav-button
             max-width: 100%
-            width: 100%
+            width: 100%
+
+// 滚动到底部按钮
+.scroll-to-bottom
+    position: fixed
+    bottom: 30px
+    right: 30px
+    width: 48px
+    height: 48px
+    background: #fff
+    border: 1px solid $border-color
+    border-radius: 50%
+    cursor: pointer
+    z-index: 999
+    display: none
+    align-items: center
+    justify-content: center
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15)
+    transition: all 0.3s ease
+    color: $text-color
+    padding: 0
+    -webkit-tap-highlight-color: transparent
+    
+    &:hover
+        background: $primary-color
+        border-color: $primary-color
+        color: #fff
+        transform: translateY(-3px)
+        box-shadow: 0 4px 12px rgba(74, 144, 226, 0.4)
+    
+    &:active
+        transform: translateY(-1px)
+        box-shadow: 0 2px 6px rgba(74, 144, 226, 0.3)
+    
+    svg
+        width: 20px
+        height: 20px
+    
+    &.show
+        display: flex
+    
+    @media mq-mobile
+        bottom: 20px
+        right: 20px
+        width: 44px
+        height: 44px
+        
+        svg
+            width: 18px
+            height: 18px