md2ui 1.0.16 → 1.0.19

package/public/docs/03-/345/257/274/350/210/252/344/270/216/345/270/203/345/261/200/02-/346/226/207/346/241/243/345/244/247/347/272/262.md

@@ -0,0 +1,51 @@
+# 文档大纲 (TOC)
+
+验证右侧文档大纲的提取、高亮和跳转功能。
+
+## 大纲提取
+
+自动从文档内容中提取 h1 ~ h6 各级标题，生成大纲列表。
+
+## 二级标题示例
+
+这是二级标题下的内容。
+
+### 三级标题示例
+
+这是三级标题下的内容。
+
+#### 四级标题示例
+
+这是四级标题下的内容。
+
+##### 五级标题示例
+
+这是五级标题下的内容。
+
+###### 六级标题示例
+
+这是六级标题下的内容。
+
+## 高亮跟随
+
+- 滚动文档时，右侧大纲自动高亮当前阅读位置对应的标题
+- 高亮判断逻辑：最后一个已滚过顶部的标题为当前激活项
+
+## 点击跳转
+
+- 点击大纲中的标题项，文档内容平滑滚动到对应位置
+- 跳转后 URL hash 更新为对应锚点
+
+## 标题锚点
+
+每个标题旁边有链接图标，点击可复制锚点链接：
+
+- 锚点 ID 使用 github-slugger 生成，语义化且稳定
+- 支持中文标题的 slug 生成
+
+## 验证要点
+
+1. 右侧大纲应列出本文档所有标题
+2. 滚动页面时，大纲中对应标题应高亮
+3. 点击大纲标题，页面应平滑滚动到对应位置
+4. 各级标题应有正确的缩进层级

package/public/docs/03-/345/257/274/350/210/252/344/270/216/345/270/203/345/261/200/03-/344/270/212/344/270/213/347/257/207/345/257/274/350/210/252.md

@@ -0,0 +1,29 @@
+# 上下篇导航
+
+验证文档底部的前后导航功能。
+
+## 功能说明
+
+- 文档底部自动显示"上一篇"和"下一篇"链接
+- 按目录树的扁平顺序计算前后关系
+- 第一篇文档只显示"下一篇"
+- 最后一篇文档只显示"上一篇"
+
+## 导航样式
+
+| 位置 | 内容 |
+| --- | --- |
+| 左侧 | 上一篇（带左箭头图标） |
+| 右侧 | 下一篇（带右箭头图标） |
+
+每个导航链接包含：
+
+- 标签文字（"上一篇"/"下一篇"）
+- 文档标题
+
+## 验证要点
+
+1. 本文档底部应显示上下篇导航
+2. 点击"上一篇"应跳转到前一个文档
+3. 点击"下一篇"应跳转到后一个文档
+4. 导航链接的标题应与目标文档一致

package/public/docs/03-/345/257/274/350/210/252/344/270/216/345/270/203/345/261/200/04-/347/253/231/345/206/205/351/223/276/346/216/245.md

@@ -0,0 +1,39 @@
+# 站内链接
+
+验证文档间的链接改写和跳转功能。
+
+## 站内文档链接
+
+以下链接指向本站其他文档，应自动改写为 SPA 路由：
+
+- [快速开始](../00-快速开始.md)
+- [功能特性](../01-功能特性.md)
+- [Mermaid 图表](../02-Markdown渲染/04-Mermaid图表.md)
+
+## 站内锚点链接
+
+以下链接指向本文档内的锚点：
+
+- [跳转到验证要点](#验证要点)
+- [跳转到外部链接](#外部链接)
+
+## 外部链接
+
+以下链接指向外部网站，应在新标签页打开：
+
+- [GitHub](https://github.com)
+- [Vue.js 官网](https://vuejs.org)
+- [Vite 官网](https://vitejs.dev)
+
+## 跨文档锚点链接
+
+以下链接指向其他文档的特定锚点：
+
+- [Frontmatter 支持的字段](../02-Markdown渲染/05-Frontmatter.md#支持的字段)
+
+## 验证要点
+
+1. 站内文档链接点击后应在当前页面加载目标文档（SPA 路由）
+2. 站内锚点链接点击后应平滑滚动到对应位置
+3. 外部链接点击后应在新标签页打开
+4. 不存在的文档链接应显示为断链样式

package/public/docs/04-/346/220/234/347/264/242/345/212/237/350/203/275/00-/345/205/250/346/226/207/346/220/234/347/264/242.md

@@ -0,0 +1,46 @@
+# 全文搜索
+
+验证全文搜索的索引构建、中文分词和搜索交互。
+
+## 搜索入口
+
+- 顶部搜索框：点击聚焦后展开下拉搜索结果
+- 快捷键 Ctrl+K（Mac 下 Cmd+K）唤起搜索框
+
+## 搜索特性
+
+| 特性 | 说明 |
+| --- | --- |
+| 中文分词 | 基于 bigram 分词，支持中文关键词搜索 |
+| 模糊匹配 | fuzzy 参数 0.2，容忍少量拼写错误 |
+| 前缀搜索 | 输入部分关键词即可匹配 |
+| 标题加权 | 标题匹配权重为内容的 3 倍 |
+| 懒加载索引 | 首次打开搜索时才构建索引 |
+
+## 搜索测试关键词
+
+以下关键词可用于测试搜索功能：
+
+- 文档渲染系统
+- Markdown 解析引擎
+- 代码语法高亮
+- Mermaid 图表绘制
+- 响应式布局适配
+- 全文检索引擎
+- Tiptap 富文本编辑器
+
+## 搜索交互
+
+1. 输入关键词，下拉列表实时显示匹配结果
+2. 键盘上下键移动选中项
+3. 回车键确认选中，跳转到对应文档
+4. ESC 键关闭搜索
+5. 搜索结果按相关度排序，最多显示 20 条
+
+## 验证要点
+
+1. Ctrl+K 应聚焦搜索框
+2. 输入"Mermaid"应匹配到 Mermaid 图表文档
+3. 输入中文关键词"布局"应匹配到相关文档
+4. 点击搜索结果应跳转到对应文档
+5. 首次搜索时应有索引构建过程

package/public/docs/05-/347/274/226/350/276/221/345/212/237/350/203/275/00-/347/274/226/350/276/221/345/231/250/345/237/272/347/241/200.md

@@ -0,0 +1,65 @@
+# 编辑器基础
+
+验证 Tiptap 富文本编辑器的各项编辑功能。
+
+## 模式切换
+
+顶部工具栏提供查看/编辑模式切换按钮：
+
+- 查看模式：渲染后的 HTML 内容，只读
+- 编辑模式：Tiptap 富文本编辑器，可编辑
+
+切换时保持阅读位置（三级策略）：
+1. 通过锚点 ID 定位
+2. 通过标题文本匹配
+3. 按滚动比例恢复
+
+## 工具栏功能
+
+### 文本格式
+
+| 功能 | 快捷键 | 说明 |
+|------|--------|------|
+| 加粗 | Ctrl+B | **粗体文本** |
+| 斜体 | Ctrl+I | *斜体文本* |
+| 下划线 | Ctrl+U | 下划线文本 |
+| 删除线 | - | ~~删除线文本~~ |
+| 行内代码 | - | `行内代码` |
+
+### 标题
+
+支持 H1 ~ H4 四级标题快速切换。
+
+### 列表
+
+- 无序列表
+- 有序列表
+- 任务列表
+
+### 块级元素
+
+- 引用块
+- 分割线
+- 代码块（支持语言标签输入，``` 输入规则触发）
+- 表格（插入 3x3 表格，支持调整大小和气泡菜单）
+- 图片（通过 URL 插入）
+
+### 撤销/重做
+
+- Ctrl+Z 撤销
+- Ctrl+Shift+Z 重做
+
+## Mermaid 编辑
+
+编辑模式下 Mermaid 代码块渲染为图表预览：
+
+- 右上角编辑按钮进入代码编辑模式
+- 编辑完成后点击"完成"按钮回到预览
+- 实时渲染图表，渲染失败时显示错误提示
+
+## 验证要点
+
+1. 点击"编辑"按钮应切换到编辑模式
+2. 工具栏各按钮应正常工作
+3. 编辑内容后切回查看模式，内容应同步更新
+4. Mermaid 代码块应显示为图表预览

package/public/docs/05-/347/274/226/350/276/221/345/212/237/350/203/275/01-/350/207/252/345/212/250/344/277/235/345/255/230.md

@@ -0,0 +1,38 @@
+# 自动保存
+
+验证编辑模式下的自动保存机制。
+
+## 保存策略
+
+| 触发条件 | 延迟 | 说明 |
+|----------|------|------|
+| 内容变更 | 1 秒防抖 | 编辑内容后 1 秒无操作自动保存 |
+| 组件卸载 | 立即 | 切换文档或退出编辑模式时立即保存 |
+
+## 工作流程
+
+1. 用户在编辑器中修改内容
+2. 每次修改触发 `onUpdate` 回调
+3. 启动 1 秒防抖定时器
+4. 1 秒内无新修改，调用 `saveDoc` API 保存
+5. 保存成功后重置文件 ETag，避免轮询误判为外部变更
+
+## 保存 API
+
+```javascript
+// POST /api/save
+{
+  path: "相对文件路径",
+  content: "Markdown 文本内容"
+}
+```
+
+- 服务端自动创建不存在的父目录
+- 路径安全检查，防止路径穿越攻击
+
+## 验证要点
+
+1. 编辑模式下修改内容，等待 1 秒后文件应自动保存
+2. 快速连续输入时，只在最后一次输入后 1 秒保存（防抖）
+3. 切换到查看模式时，未保存的内容应立即保存
+4. 切换到其他文档时，当前文档应立即保存

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 路由应正确解析