md2ui 1.0.18 → 1.0.20

package/public/docs/06-/351/230/205/350/257/273/344/275/223/351/252/214/00-/351/230/205/350/257/273/350/277/233/345/272/246.md

@@ -0,0 +1,43 @@
+# 阅读进度
+
+验证阅读进度条和阅读时间显示功能。
+
+## 进度条
+
+- 右下角浮动按钮显示当前滚动百分比（如 42%）
+- 滚动超过 300px 后按钮出现
+- 点击按钮返回顶部（平滑滚动）
+
+## 阅读时间
+
+文档标题下方显示元信息：
+
+- 字数统计（去除 frontmatter、代码块、HTML 标签后计算）
+- 预计阅读时间（中文 400 字/分钟，英文 200 词/分钟）
+
+## 填充内容
+
+以下为填充内容，用于测试滚动进度计算。
+
+### 第一章
+
+在软件开发领域，文档的重要性不言而喻。一份好的文档不仅能帮助开发者快速上手项目，还能降低团队沟通成本，提高协作效率。Markdown 作为一种轻量级标记语言，因其简洁的语法和良好的可读性，已经成为技术文档的事实标准。
+
+### 第二章
+
+md2ui 的设计理念是"零配置即可使用"。只需一行命令，就能将本地的 Markdown 文件转换为美观的网页。不需要复杂的配置文件，不需要学习新的模板语法，只需要专注于内容本身。
+
+### 第三章
+
+三栏布局是文档站点的经典设计。左侧导航帮助用户快速定位文档，中间内容区提供舒适的阅读体验，右侧大纲方便在长文档中跳转。所有栏目都支持拖拽调整宽度，也可以折叠隐藏，适应不同的屏幕尺寸和阅读习惯。
+
+### 第四章
+
+全文搜索是文档工具的核心功能之一。md2ui 使用 MiniSearch 作为搜索引擎，支持中文 bigram 分词、模糊匹配和前缀搜索。搜索索引采用懒加载策略，只在用户首次打开搜索时构建，避免影响页面加载速度。
+
+## 验证要点
+
+1. 滚动本文档，右下角应显示进度百分比
+2. 滚动超过 300px 后返回顶部按钮应出现
+3. 点击返回顶部按钮，页面应平滑滚动到顶部
+4. 文档标题下方应显示字数和预计阅读时间

package/public/docs/06-/351/230/205/350/257/273/344/275/223/351/252/214/01-/345/233/276/347/211/207/346/224/276/345/244/247.md

@@ -0,0 +1,40 @@
+# 图片放大
+
+验证图片点击放大和多图切换功能。
+
+## 图片展示
+
+以下图片应支持点击放大查看：
+
+![Vue Logo](/logo.svg)\## 放大功能
+
+- 点击图片弹出放大浮层
+- 放大浮层显示图片原始尺寸
+- 点击浮层背景或按 ESC 关闭
+
+## 多图切换
+
+当文档中有多张图片时：
+
+- 放大浮层支持左右切换图片
+- 显示当前图片索引
+
+## Mermaid 图表放大
+
+Mermaid 渲染后的图表也支持点击放大：
+
+```mermaid
+graph LR
+    A[输入 Markdown] --> B[解析渲染]
+    B --> C[HTML 输出]
+    C --> D[图片放大支持]
+```
+
+## 验证要点
+
+1. 点击上方 Vue Logo 图片，应弹出放大浮层
+2. 放大浮层中图片应清晰显示
+3. 点击背景或按 ESC 应关闭浮层
+4. 点击 Mermaid 图表也应支持放大
+
+   ![](/docs/06-阅读体验/assets/img-1777261394722.png)

package/public/docs/06-/351/230/205/350/257/273/344/275/223/351/252/214/02-/350/277/224/345/233/236/351/241/266/351/203/250.md

@@ -0,0 +1,38 @@
+# 返回顶部
+
+验证返回顶部按钮的显示和交互。
+
+## 触发条件
+
+- 页面滚动超过 300px 时，右下角显示返回顶部按钮
+- 按钮上显示当前滚动进度百分比
+- 滚动回 300px 以内时按钮自动隐藏
+
+## 按钮样式
+
+- 圆形浮动按钮，固定在右下角
+- 包含向上箭头图标和进度文字
+- 带有淡入淡出动画效果
+
+## 填充内容
+
+以下为填充内容，确保页面可滚动。
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+在前端开发中，用户体验的细节往往决定了产品的品质。返回顶部按钮虽然是一个小功能，但对于长文档的阅读体验至关重要。当用户阅读到文档底部时，一键返回顶部比手动滚动要方便得多。
+
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+文档工具的设计需要在功能丰富和使用简洁之间找到平衡。太多的功能会增加学习成本，太少的功能又无法满足需求。md2ui 的目标是提供恰到好处的功能集，让用户专注于内容本身。
+
+Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
+
+技术文档的可读性不仅取决于内容质量，还取决于排版和交互设计。合理的字体大小、行高、段落间距，以及清晰的标题层级，都能显著提升阅读体验。
+
+## 验证要点
+
+1. 向下滚动本文档，返回顶部按钮应出现
+2. 按钮上应显示当前滚动百分比
+3. 点击按钮，页面应平滑滚动到顶部
+4. 滚动到顶部后，按钮应自动隐藏

package/public/docs/07-/347/247/273/345/212/250/347/253/257/351/200/202/351/205/215/00-/345/223/215/345/272/224/345/274/217/345/270/203/345/261/200.md

@@ -0,0 +1,37 @@
+# 响应式布局
+
+验证移动端适配的各项功能。
+
+## 断点设计
+
+| 屏幕宽度 | 模式 | 布局变化 |
+| --- | --- | --- |
+| > 768px | 桌面端 | 三栏布局，侧边栏常驻 |
+| <= 768px | 移动端 | 单栏布局，抽屉式导航 |
+
+## 移动端特性
+
+### 抽屉式导航
+
+- 侧边栏以抽屉形式从左侧滑出
+- 打开时显示半透明遮罩
+- 点击遮罩关闭抽屉
+
+### 移动端顶栏
+
+- 独立的移动端 Header 组件
+- 包含汉堡菜单按钮、Logo、搜索按钮
+
+### 移动端 TOC
+
+- 底部浮动目录面板
+- 点击按钮展开/收起
+- 选择标题后自动关闭面板
+
+## 验证要点
+
+1. 将浏览器窗口缩小到 768px 以下，应切换为移动端布局
+2. 点击汉堡菜单按钮，侧边栏应以抽屉形式弹出
+3. 点击遮罩应关闭抽屉
+4. 底部应显示 TOC 浮动按钮
+5. 恢复窗口宽度后应自动切回桌面端布局

package/public/docs/08-/346/226/207/346/241/243/347/256/241/347/220/206/00-/346/226/260/345/273/272/344/270/216/345/210/240/351/231/244.md

@@ -0,0 +1,47 @@
+# 新建与删除
+
+验证侧边栏的文档/目录创建和删除功能。
+
+## 新建文档
+
+1. 点击侧边栏"文档目录"旁的 `+` 按钮
+2. 选择"新建文档"或"新建目录"
+3. 输入名称，点击确定
+
+### 新建规则
+
+| 规则 | 说明 |
+|------|------|
+| 名称不能为空 | 提示"名称不能为空" |
+| 禁止特殊字符 | `\ / : * ? " < > \|` 不允许 |
+| 不能重名 | 同目录下已存在同名文件/目录时提示 |
+
+### 在子目录下新建
+
+- 右键点击文件夹节点的 `+` 按钮
+- 新建的文件/目录会创建在该文件夹下
+
+## 删除文档
+
+1. 右键点击文档/目录节点的删除按钮
+2. 弹出确认弹窗
+3. 确认后删除
+
+### 删除规则
+
+- 删除文件：直接删除
+- 删除目录：递归删除目录下所有内容，弹窗会提示"目录下的所有内容将被一并删除"
+
+## 文件热更新
+
+- 文件列表变化后自动刷新导航树（轮询 + ETag 机制）
+- 当前文档内容变化后自动刷新内容
+- 轮询间隔 1 秒
+
+## 验证要点
+
+1. 点击 `+` 按钮应弹出新建菜单
+2. 新建文档后应立即出现在导航树中
+3. 删除文档前应弹出确认弹窗
+4. 删除后文档应从导航树中消失
+5. 外部修改文件后，页面应自动刷新

package/public/docs/09-/345/257/274/345/207/272/345/212/237/350/203/275/00-/345/257/274/345/207/272Word.md

@@ -0,0 +1,77 @@
+# 导出 Word
+
+验证文档导出为 .docx 文件的功能。
+
+## 使用方式
+
+顶部工具栏点击"导出 Word"按钮，即可将当前文档导出为 .docx 文件。
+
+## 支持的元素
+
+| 元素 | 导出效果 |
+|------|----------|
+| 标题 h1~h6 | 对应 Word 标题级别 |
+| 段落 | 正文段落 |
+| 粗体/斜体/删除线 | 对应文本格式 |
+| 行内代码 | Consolas 字体 + 灰色背景 |
+| 超链接 | 可点击的蓝色链接 |
+| 无序/有序列表 | 带缩进的列表 |
+| 任务列表 | [x] / [ ] 前缀文本 |
+| 引用块 | 左侧边框 + 灰色背景 |
+| 代码块 | 等宽字体 + 灰色背景 + 边框 |
+| 表格 | 固定布局表格，兼容 Office + WPS |
+| 图片 | 嵌入图片（限制最大宽度 6 英寸） |
+| Mermaid 图表 | SVG 转 PNG 后嵌入 |
+| 水平线 | 底部边框线 |
+
+## 导出配置
+
+- 字体：Microsoft YaHei（微软雅黑）
+- 正文字号：11pt
+- 行距：1.5 倍
+- 页边距：上下 1 英寸，左右 1.2 英寸
+
+## 以下内容用于测试导出效果
+
+### 文本格式
+
+**粗体**、*斜体*、~~删除线~~、`行内代码`
+
+### 链接
+
+[GitHub](https://github.com)
+
+### 列表
+
+- 无序列表项 1
+- 无序列表项 2
+
+1. 有序列表项 1
+2. 有序列表项 2
+
+### 引用
+
+> 这是一段引用文本，用于测试导出效果。
+
+### 代码块
+
+```javascript
+function hello() {
+  console.log('Hello, md2ui!')
+}
+```
+
+### 表格
+
+| 功能 | 状态 |
+|------|------|
+| 标题导出 | 已支持 |
+| 表格导出 | 已支持 |
+| 图表导出 | 已支持 |
+
+## 验证要点
+
+1. 点击"导出 Word"按钮应下载 .docx 文件
+2. 用 Word 或 WPS 打开，各元素格式应正确
+3. 表格应正确显示行列结构
+4. 导出过程中按钮应显示"导出中..."

package/public/docs/10-/351/203/250/347/275/262/344/270/216/351/205/215/347/275/256/00-CLI/345/267/245/345/205/267.md

@@ -0,0 +1,52 @@
+# CLI 工具
+
+验证 md2ui 命令行工具的各项功能。
+
+## 基本用法
+
+```bash
+# 在文档目录下启动预览
+cd /path/to/your/docs
+md2ui
+
+# 指定端口
+md2ui -p 8080
+
+# 静态构建
+md2ui build
+```
+
+## 启动流程
+
+1. 扫描当前目录下的 `.md` 文件
+2. 加载用户配置文件（如果存在）
+3. 启动 Vite 开发服务器
+4. 自动打开浏览器
+
+## 配置文件加载
+
+CLI 按以下顺序查找配置文件：
+
+| 优先级 | 文件名 | 格式 |
+|--------|--------|------|
+| 1 | `md2ui.config.js` | ES Module |
+| 2 | `.md2uirc.json` | JSON |
+
+命令行参数优先级最高，会覆盖配置文件中的同名配置。
+
+## 服务端 API
+
+开发服务器提供以下 API：
+
+| 路径 | 方法 | 说明 |
+|------|------|------|
+| `/@user-docs-list` | GET | 文档列表 |
+| `/@site-config` | GET | 站点配置 |
+| `/@user-docs/{path}` | GET | 文档内容 |
+
+## 验证要点
+
+1. 在包含 .md 文件的目录下运行 `md2ui` 应启动服务
+2. 无 .md 文件时应提示错误并退出
+3. `-p` 参数应正确设置端口
+4. 配置文件应被正确加载

package/public/docs/10-/351/203/250/347/275/262/344/270/216/351/205/215/347/275/256/01-SSG/351/235/231/346/200/201/346/236/204/345/273/272.md

@@ -0,0 +1,44 @@
+# SSG 静态构建
+
+验证 `md2ui build` 静态站点生成功能。
+
+## 使用方式
+
+```bash
+md2ui build
+```
+
+## 构建产物
+
+构建完成后在 `dist/` 目录下生成纯静态文件：
+
+```
+dist/
+├── index.html          # 入口页面
+├── assets/             # JS/CSS 资源
+└── docs/               # 文档文件
+```
+
+## 部署方式
+
+生成的静态文件可部署到任意静态服务器：
+
+| 平台 | 说明 |
+|------|------|
+| GitHub Pages | 推送 dist 目录到 gh-pages 分支 |
+| Vercel | 配置输出目录为 dist |
+| Nginx | 将 dist 目录配置为网站根目录 |
+| CDN | 上传 dist 目录到 CDN 存储 |
+
+## SPA 路由
+
+- 基于 hash 的文档路由
+- 支持浏览器前进/后退
+- 支持直接通过 URL 访问特定文档
+
+## 验证要点
+
+1. 运行 `md2ui build` 应在 dist 目录生成静态文件
+2. 用静态服务器打开 dist/index.html 应正常显示
+3. 文档导航和内容加载应正常工作
+4. URL 路由应正确解析

package/public/docs/10-/351/203/250/347/275/262/344/270/216/351/205/215/347/275/256/02-/350/207/252/345/256/232/344/271/211/351/205/215/347/275/256.md

@@ -0,0 +1,58 @@
+# 自定义配置
+
+验证用户自定义配置的加载和生效。
+
+## 配置文件
+
+在文档目录下创建 `md2ui.config.js` 或 `.md2uirc.json`：
+
+```js
+// md2ui.config.js
+export default {
+  title: '我的文档站',
+  port: 8080,
+  folderExpanded: true,
+  themeColor: '#3eaf7c',
+  github: 'https://github.com/xiaoyaodev/md2ui',
+  footer: 'Copyright © 2025'
+}
+```
+
+## 配置项
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| title | string | `'md2ui'` | 站点标题，显示在顶部 Logo 旁 |
+| port | number | `3000` | 开发服务器端口 |
+| folderExpanded | boolean | `false` | 文件夹默认是否展开 |
+| themeColor | string | `'#3eaf7c'` | 主题色，影响全局强调色 |
+| github | string | `''` | GitHub 仓库链接，显示在顶部 |
+| footer | string | `''` | 页脚内容 |
+
+## JSON 格式
+
+```json
+{
+  "title": "我的文档站",
+  "port": 8080,
+  "folderExpanded": true,
+  "themeColor": "#3eaf7c",
+  "github": "https://github.com/xiaoyaodev/md2ui",
+  "footer": "Copyright © 2025"
+}
+```
+
+## 优先级
+
+配置合并优先级（从低到高）：
+
+1. 内置默认值
+2. 配置文件（md2ui.config.js 或 .md2uirc.json）
+3. 命令行参数（如 `-p 8080`）
+
+## 验证要点
+
+1. 创建配置文件后重启服务，配置应生效
+2. 修改 title 后页面标题应更新
+3. 修改 themeColor 后主题色应变化
+4. 命令行 `-p` 参数应覆盖配置文件中的 port

package/public/docs/11-/345/244/232/347/272/247/347/233/256/345/275/225/346/265/213/350/257/225/00-/344/270/200/347/272/247/346/226/207/346/241/243.md

@@ -0,0 +1,20 @@
+# 一级文档
+
+这是多级目录测试的一级文档，用于验证目录树的多级嵌套显示。
+
+## 目录结构
+
+```
+11-多级目录测试/
+├── 01-一级文档.md          ← 当前文档
+└── 01-子目录/
+    ├── 01-二级文档.md
+    └── 01-深层嵌套/
+        └── 01-三级文档.md
+```
+
+## 验证要点
+
+1. 左侧导航应正确显示三级嵌套结构
+2. 文件夹节点应可展开/收起
+3. 各级文档应可正常点击加载

package/public/docs/11-/345/244/232/347/272/247/347/233/256/345/275/225/346/265/213/350/257/225/01-/345/255/220/347/233/256/345/275/225/00-/344/272/214/347/272/247/346/226/207/346/241/243.md

@@ -0,0 +1,13 @@
+# 二级文档
+
+这是多级目录测试的二级文档，位于 `01-子目录` 下。
+
+## 站内链接测试
+
+- [返回一级文档](../01-一级文档.md)
+- [进入三级文档](01-深层嵌套/01-三级文档.md)
+
+## 验证要点
+
+1. 本文档应在导航树的第二级显示
+2. 上方站内链接应可正常跳转

package/public/docs/11-/345/244/232/347/272/247/347/233/256/345/275/225/346/265/213/350/257/225/01-/345/255/220/347/233/256/345/275/225/01-/346/267/261/345/261/202/345/265/214/345/245/227/00-/344/270/211/347/272/247/346/226/207/346/241/243.md

@@ -0,0 +1,23 @@
+# 三级文档
+
+这是多级目录测试的三级文档，位于 `01-子目录/01-深层嵌套` 下。
+
+## 深层嵌套验证
+
+本文档验证三级及以上目录嵌套的正确性：
+
+- 导航树应正确缩进显示
+- 文件夹展开/收起应正常工作
+- 上下篇导航应正确计算
+
+## 站内链接测试
+
+- [返回二级文档](../01-二级文档.md)
+- [返回一级文档](../../01-一级文档.md)
+- [跳转到快速开始](../../../00-快速开始.md)
+
+## 验证要点
+
+1. 本文档应在导航树的第三级显示
+2. 多级返回链接应可正常跳转
+3. 跨多级目录的链接应正确解析