md2ui 1.0.18 → 1.0.20

package/public/docs/03-/345/257/274/350/210/252/344/270/216/345/270/203/345/261/200/00-/344/270/211/346/240/217/345/270/203/345/261/200.md

@@ -0,0 +1,33 @@
+# 三栏布局
+
+验证三栏布局的显示效果和交互行为。
+
+## 布局结构
+
+界面采用经典的三栏布局：
+
+| 区域 | 位置 | 功能 |
+|------|------|------|
+| 侧边栏 | 左侧 | 文档导航树 |
+| 内容区 | 中间 | 文档内容渲染 |
+| 大纲栏 | 右侧 | 文档标题大纲 |
+
+## 拖拽调整宽度
+
+- 侧边栏和内容区之间有拖拽条，可调整侧边栏宽度（200~400px）
+- 内容区和大纲栏之间有拖拽条，可调整大纲栏宽度（200~400px）
+- 拖拽时鼠标变为 `col-resize` 样式
+
+## 折叠与展开
+
+- 侧边栏可通过左上角按钮收起，收起后显示展开按钮
+- 大纲栏可通过右上角按钮收起，收起后显示展开按钮
+- 折叠后内容区自动占满剩余空间
+
+## 验证要点
+
+1. 拖拽左侧分隔条，侧边栏宽度应在 200~400px 范围内变化
+2. 拖拽右侧分隔条，大纲栏宽度应在 200~400px 范围内变化
+3. 点击侧边栏收起按钮，侧边栏应隐藏
+4. 点击大纲栏收起按钮，大纲栏应隐藏
+5. 收起后点击展开按钮，对应栏目应恢复

package/public/docs/03-/345/257/274/350/210/252/344/270/216/345/270/203/345/261/200/01-/347/233/256/345/275/225/346/240/221/345/257/274/350/210/252.md

@@ -0,0 +1,43 @@
+# 目录树导航
+
+验证侧边栏目录树的自动生成、排序和交互功能。
+
+## 自动生成
+
+- 递归扫描文档文件夹下的所有 `.md` 文件和子目录
+- 自动生成多级树形导航结构
+- 文件夹显示为可展开/收起的节点
+
+## 排序规则
+
+使用 `序号-名称` 格式控制排序：
+
+| 文件名 | 显示名称 | 排序 |
+|--------|----------|------|
+| `00-快速开始.md` | 快速开始 | 0 |
+| `01-功能特性.md` | 功能特性 | 1 |
+| `02-Markdown渲染/` | Markdown渲染 | 2 |
+
+序号越小越靠前，无序号的文件排在最后。
+
+## 导航过滤
+
+侧边栏顶部有过滤输入框：
+
+- 输入关键词实时过滤匹配的文档名
+- 过滤时自动展开包含匹配项的文件夹
+- 清空输入恢复完整目录树
+- 无匹配结果时显示"没有匹配的文档"
+
+## 全部展开/收起
+
+- 点击"全部展开"按钮，所有文件夹节点展开
+- 点击"全部收起"按钮，所有文件夹节点收起
+
+## 验证要点
+
+1. 左侧导航应正确显示当前文档目录结构
+2. 点击文件夹节点应展开/收起子节点
+3. 在过滤框输入关键词，应实时过滤文档列表
+4. 点击文档节点应加载对应文档内容
+5. 当前文档应在导航中高亮显示

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/03-/345/257/274/350/210/252/344/270/216/345/270/203/345/261/200/05-/345/244/247/347/272/262/345/216/213/345/212/233/346/265/213/350/257/225.md

@@ -0,0 +1,340 @@
+# 大纲压力测试
+
+本文档用于测试右侧文档大纲（TOC）在大量标题锚点场景下的显示效果、滚动跟随和点击跳转功能。文档包含从 h1 到 h6 各级标题，总计超过 40 个锚点。
+
+## 第一章 项目概述
+
+本章介绍项目的基本背景和目标定位，帮助读者快速了解项目全貌。
+
+项目启动于 2024 年初，旨在构建一套轻量级的文档站点生成工具。核心理念是让开发者专注于内容创作，而非繁琐的站点配置。我们希望通过简洁的设计和强大的功能，降低文档维护的门槛。
+
+### 1.1 背景介绍
+
+随着开源生态的蓬勃发展，越来越多的项目需要高质量的文档支持。然而现有的文档工具要么过于复杂，要么功能不足，难以满足中小型项目的需求。
+
+在调研了市面上主流的文档工具后，我们发现大多数工具存在以下问题：配置繁琐、构建缓慢、定制困难。因此我们决定从零开始，打造一款真正好用的文档工具。
+
+#### 1.1.1 行业现状
+
+当前文档工具市场呈现两极分化的趋势。一方面是功能全面但学习曲线陡峭的重型方案，如 Docusaurus、GitBook 等；另一方面是轻量但功能有限的简易方案，如纯静态 Markdown 渲染器。
+
+我们的目标是在两者之间找到平衡点，提供开箱即用的体验，同时保留足够的扩展能力。
+
+##### 1.1.1.1 国内生态
+
+国内开发者对中文文档的支持有着特殊需求，包括中文搜索、中文排版优化、中文锚点生成等。这些细节往往被国外工具忽略，导致使用体验不佳。
+
+我们在设计之初就将中文支持作为一等公民，确保所有功能在中文环境下都能完美运行。
+
+###### 1.1.1.1.1 社区反馈
+
+通过社区调研，我们收集到了大量用户反馈。超过 70% 的用户表示希望有一款支持中文的轻量级文档工具。这坚定了我们的开发方向。
+
+###### 1.1.1.1.2 竞品分析
+
+我们对比了 VitePress、Docusaurus、Nextra、Rspress 等主流方案，分析了各自的优缺点，最终确定了差异化的产品定位。
+
+##### 1.1.1.2 国际趋势
+
+从全球范围来看，文档即代码（Docs as Code）的理念正在被越来越多的团队接受。Markdown 作为文档格式的事实标准，其生态也在不断完善。
+
+#### 1.1.2 技术选型
+
+经过多轮评估，我们最终选择了以下技术栈：
+
+- 前端框架：Vue 3 + Composition API
+- 构建工具：Vite
+- Markdown 解析：markdown-it
+- 编辑器：Tiptap
+- 样式方案：Tailwind CSS
+
+### 1.2 目标定位
+
+我们的目标是打造一款面向中小型项目的文档工具，核心特点包括：零配置启动、实时预览、全文搜索、多端适配。
+
+#### 1.2.1 核心用户
+
+主要面向以下用户群体：
+
+1. 开源项目维护者
+2. 技术团队内部文档管理
+3. 个人知识库搭建
+4. 产品帮助文档编写
+
+#### 1.2.2 使用场景
+
+典型的使用场景包括 API 文档、使用指南、架构设计文档、团队规范文档等。无论是公开的开源文档还是私有的内部文档，都能很好地支持。
+
+## 第二章 架构设计
+
+本章深入介绍系统的整体架构设计，包括前端架构、数据流和模块划分。
+
+### 2.1 整体架构
+
+系统采用经典的三层架构：展示层、逻辑层、数据层。展示层负责 UI 渲染和用户交互，逻辑层处理业务规则和状态管理，数据层负责文档的读取和持久化。
+
+整体架构遵循单向数据流的原则，所有状态变更都通过明确的路径传递，便于调试和维护。
+
+#### 2.1.1 前端架构
+
+前端采用 Vue 3 的 Composition API 进行开发，通过 composables 模式组织可复用逻辑。主要模块包括：
+
+- 文档树管理（useDocTree）
+- 文档内容管理（useDocManager）
+- 搜索功能（useSearch）
+- 滚动控制（useScroll）
+- 移动端适配（useMobile）
+
+每个 composable 职责单一，通过组合的方式构建复杂功能，避免了传统 Options API 中逻辑分散的问题。
+
+##### 2.1.1.1 组件设计
+
+组件按照功能域划分，遵循单一职责原则。核心组件包括 AppSidebar（侧边栏）、DocContent（文档内容）、TableOfContents（目录大纲）、SearchPanel（搜索面板）等。
+
+每个组件都有清晰的 props 和 events 接口定义，组件间通过 provide/inject 或事件总线进行通信。
+
+###### 2.1.1.1.1 渲染组件
+
+渲染组件负责将 Markdown 内容转换为可视化的 HTML。支持代码高亮、数学公式、Mermaid 图表等扩展语法。渲染过程采用增量更新策略，避免不必要的 DOM 操作。
+
+###### 2.1.1.1.2 交互组件
+
+交互组件处理用户操作，如搜索、导航、编辑等。所有交互都经过防抖和节流处理，确保流畅的用户体验。
+
+##### 2.1.1.2 状态管理
+
+项目没有引入 Vuex 或 Pinia 等状态管理库，而是通过 Vue 3 的 reactive API 和 composables 模式实现轻量级状态管理。这种方式更加灵活，也减少了不必要的依赖。
+
+#### 2.1.2 数据流设计
+
+数据流遵循单向流动原则：用户操作 -> 状态更新 -> 视图渲染。文档数据通过 API 层获取，经过解析和转换后存入响应式状态，最终驱动视图更新。
+
+### 2.2 模块划分
+
+系统按照功能域划分为以下核心模块，每个模块独立开发、独立测试。
+
+#### 2.2.1 文档解析模块
+
+负责将 Markdown 源文件解析为结构化数据。支持标准 Markdown 语法以及多种扩展语法，包括 Frontmatter、数学公式、Mermaid 图表等。
+
+解析过程分为两个阶段：词法分析和语法分析。词法分析将源文本拆分为 token 序列，语法分析将 token 序列转换为 AST（抽象语法树）。
+
+#### 2.2.2 路由模块
+
+路由模块基于 hash 模式实现，将 URL 路径映射到对应的文档文件。支持多级目录结构和中文路径，确保文档链接的稳定性和可分享性。
+
+#### 2.2.3 搜索模块
+
+搜索模块实现了全文搜索功能，支持中文分词和关键词高亮。搜索索引在文档加载时构建，采用倒排索引结构，确保搜索响应速度。
+
+#### 2.2.4 编辑模块
+
+编辑模块基于 Tiptap 编辑器实现，支持所见即所得的 Markdown 编辑体验。编辑器内置了丰富的工具栏和快捷键，降低了 Markdown 的学习门槛。
+
+### 2.3 性能优化
+
+性能是我们始终关注的重点。通过多种优化手段，确保文档站点在各种设备上都能流畅运行。
+
+#### 2.3.1 懒加载策略
+
+文档内容采用按需加载策略，只有当用户导航到某个文档时才会请求其内容。同时对图片和代码块实现了视口内懒加载，减少初始加载时间。
+
+#### 2.3.2 缓存机制
+
+多层缓存机制确保重复访问的文档能够快速展示。包括内存缓存、浏览器缓存和 Service Worker 缓存三个层级，根据数据的时效性选择合适的缓存策略。
+
+## 第三章 功能实现
+
+本章详细介绍各核心功能的实现细节和技术方案。
+
+### 3.1 Markdown 渲染
+
+Markdown 渲染是文档工具的核心能力。我们基于 markdown-it 实现了完整的渲染管线，支持标准语法和多种扩展。
+
+渲染管线的设计遵循插件化原则，每种扩展语法都通过独立的插件实现，便于维护和扩展。
+
+#### 3.1.1 代码高亮
+
+代码高亮基于 highlight.js 实现，支持超过 180 种编程语言的语法高亮。同时提供了行号显示、代码复制、语言标签等增强功能。
+
+##### 3.1.1.1 主题定制
+
+支持自定义代码高亮主题，内置了多套配色方案。用户可以通过 CSS 变量轻松切换主题，也可以完全自定义配色。
+
+##### 3.1.1.2 性能优化
+
+对于超长代码块，采用虚拟滚动技术，只渲染视口内的代码行，避免大量 DOM 节点导致的性能问题。
+
+#### 3.1.2 数学公式
+
+数学公式渲染基于 KaTeX 实现，支持行内公式和块级公式。KaTeX 相比 MathJax 有更快的渲染速度，适合文档场景。
+
+行内公式示例：$E = mc^2$，块级公式支持复杂的数学表达式。
+
+#### 3.1.3 图表渲染
+
+Mermaid 图表渲染支持流程图、时序图、甘特图、类图等多种图表类型。图表在文档加载时异步渲染，不阻塞主内容的展示。
+
+### 3.2 导航系统
+
+导航系统是文档站点的骨架，决定了用户浏览文档的效率和体验。
+
+#### 3.2.1 目录树
+
+左侧目录树支持多级嵌套，自动从文件系统结构生成。支持展开/折叠、当前文档高亮、拖拽排序等交互功能。
+
+目录树的数据结构采用递归树形结构，每个节点包含标题、路径、子节点等信息。
+
+##### 3.2.1.1 排序规则
+
+文档排序支持两种模式：文件名前缀排序（如 00-、01-）和自然排序。前缀排序适合需要精确控制顺序的场景，自然排序适合随意组织的文档。
+
+##### 3.2.1.2 图标系统
+
+目录树中的图标根据节点类型自动匹配：文件夹使用目录图标，文档使用文件图标。展开/折叠状态也有对应的图标变化。
+
+#### 3.2.2 文档大纲
+
+右侧文档大纲从当前文档内容中提取各级标题，生成可点击的导航列表。支持滚动跟随高亮和点击平滑跳转。
+
+这正是本文档重点测试的功能。当标题数量很多时，大纲列表需要自身支持滚动，并且保持良好的可读性。
+
+#### 3.2.3 面包屑导航
+
+顶部面包屑显示当前文档在目录树中的完整路径，方便用户了解当前位置和快速跳转到上级目录。
+
+#### 3.2.4 上下篇导航
+
+文档底部提供上一篇和下一篇的导航链接，方便用户按顺序阅读文档。导航顺序与目录树的排列顺序一致。
+
+### 3.3 搜索功能
+
+全文搜索是提升文档可用性的关键功能。用户可以通过关键词快速定位到目标内容。
+
+#### 3.3.1 索引构建
+
+搜索索引在文档首次加载时构建，采用倒排索引结构。索引数据存储在内存中，支持增量更新。对于大型文档站点，索引构建过程在 Web Worker 中异步执行，不阻塞主线程。
+
+#### 3.3.2 中文分词
+
+中文搜索的核心挑战是分词。我们采用了基于字典的正向最大匹配算法，结合 N-gram 模型，实现了较好的中文分词效果。
+
+#### 3.3.3 结果排序
+
+搜索结果按照相关度排序，综合考虑关键词出现频率、位置权重（标题 > 正文）、文档权重等因素。排序算法参考了 BM25 模型。
+
+### 3.4 编辑功能
+
+内置编辑器让用户可以直接在浏览器中编辑文档，无需切换到代码编辑器。
+
+#### 3.4.1 所见即所得
+
+基于 Tiptap 实现的所见即所得编辑器，用户在编辑时就能看到最终的渲染效果。支持常用的格式化操作，如加粗、斜体、列表、链接等。
+
+#### 3.4.2 自动保存
+
+编辑器支持自动保存功能，在用户停止输入一段时间后自动将内容保存到服务端。同时提供手动保存的快捷键（Ctrl+S）。
+
+#### 3.4.3 协同编辑
+
+未来计划支持多人协同编辑，基于 CRDT 算法实现冲突解决。目前已预留了协同编辑的接口设计。
+
+## 第四章 部署方案
+
+本章介绍项目的部署方式和配置选项。
+
+### 4.1 CLI 工具
+
+提供命令行工具 `markdoc` 用于项目初始化、开发预览和生产构建。
+
+#### 4.1.1 初始化命令
+
+通过 `markdoc init` 命令可以快速创建一个新的文档项目，自动生成目录结构和配置文件。
+
+#### 4.1.2 开发模式
+
+`markdoc dev` 启动本地开发服务器，支持热更新和实时预览。开发服务器基于 Vite 构建，启动速度极快。
+
+#### 4.1.3 生产构建
+
+`markdoc build` 执行生产构建，生成优化后的静态文件。构建过程包括代码压缩、资源优化、预渲染等步骤。
+
+### 4.2 静态部署
+
+构建产物为纯静态文件，可以部署到任何静态文件托管服务。
+
+#### 4.2.1 GitHub Pages
+
+支持一键部署到 GitHub Pages，通过 GitHub Actions 实现自动化构建和部署。只需在仓库中添加工作流配置文件即可。
+
+#### 4.2.2 Vercel
+
+Vercel 部署同样简单，连接 Git 仓库后自动检测项目类型并完成部署。支持自定义域名和 HTTPS。
+
+#### 4.2.3 Nginx
+
+对于自建服务器的场景，提供了 Nginx 配置模板。包括 gzip 压缩、缓存策略、SPA 路由回退等最佳实践配置。
+
+### 4.3 自定义配置
+
+通过配置文件可以自定义站点的各项参数。
+
+#### 4.3.1 站点信息
+
+配置站点标题、描述、Logo、favicon 等基本信息。这些信息会显示在页面标题栏和浏览器标签页中。
+
+#### 4.3.2 主题配置
+
+支持自定义主题色、字体、间距等样式参数。通过 CSS 变量实现，修改简单且不影响功能。
+
+#### 4.3.3 插件系统
+
+预留了插件系统的扩展接口，允许用户通过插件扩展文档站点的功能。插件可以注册新的 Markdown 语法、添加页面组件、扩展构建流程等。
+
+## 第五章 测试与质量
+
+本章介绍项目的测试策略和质量保障措施。
+
+### 5.1 单元测试
+
+核心模块都有对应的单元测试，覆盖率目标为 80% 以上。测试框架使用 Vitest，与 Vite 生态无缝集成。
+
+#### 5.1.1 工具函数测试
+
+工具函数的测试最为直接，输入输出明确，易于编写和维护。包括路径处理、字符串转换、数据格式化等函数的测试。
+
+#### 5.1.2 Composable 测试
+
+Composable 的测试需要模拟 Vue 的响应式环境。通过 @vue/test-utils 提供的工具函数，可以在测试中创建响应式上下文。
+
+### 5.2 集成测试
+
+集成测试验证多个模块协同工作的正确性，重点关注数据流和状态同步。
+
+### 5.3 E2E 测试
+
+端到端测试基于 Playwright 实现，模拟真实用户操作验证完整的功能流程。测试覆盖了文档浏览、搜索、编辑、导航等核心场景。
+
+## 第六章 未来规划
+
+本章展望项目的未来发展方向和计划中的新功能。
+
+### 6.1 国际化支持
+
+计划支持多语言文档，允许同一文档提供不同语言的版本。语言切换通过 URL 前缀或下拉菜单实现。
+
+### 6.2 版本管理
+
+支持文档的多版本管理，用户可以查看不同版本的文档内容。版本切换不影响当前的浏览位置。
+
+### 6.3 AI 辅助
+
+探索 AI 技术在文档领域的应用，包括智能搜索、自动摘要、翻译辅助、写作建议等功能。
+
+### 6.4 性能监控
+
+内置性能监控面板，实时展示页面加载时间、渲染性能、内存占用等指标，帮助开发者优化文档站点的性能。
+
+---
+
+以上内容包含了从 h1 到 h6 共六个层级、超过 40 个标题锚点，用于验证右侧文档大纲在大量标题场景下的显示效果、滚动行为和交互体验。

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. 切换到其他文档时，当前文档应立即保存