VitePress Pro 设计文档
约 1693 字大约 6 分钟
2025-11-23
作者：yumengjh
项目愿景：打造“动态、可扩展、可分片、可懒加载”的下一代文档系统。
基于 VitePress 的体验，但能力远超 VitePress。
项目愿景（Why）
传统 VitePress 有几个硬伤：
- ❌ 静态构建：文档更新必须构建 → 大文档构建时间长
- ❌ 超大文档卡顿：15k 字、30k 字的文档加载极慢
- ❌ 缺少后台系统：无法在线管理文档
- ❌ 无法动态获取内容（VitePress 本身是静态站点生成器）
- ❌ 无法跨端版本管理、多用户协作
而且你希望：
- 做一个 有挑战性的、长期迭代的、专业级文档系统框架
- 让自己技术提升，并做成产品级工程
于是，VitePress Pro 的核心目标是：
用 VitePress 的体验，做一个 Notion / GitBook / Vercel Docs 级别的 动态文档平台。
总体能力目标
VitePress Pro = 动态渲染器 + 文档数据库 + 分片系统 + 懒加载引擎 + 搜索引擎 + 版本系统
主要能力：
- Markdown 动态渲染（无需构建）
- 文档分片（标题 + 智能分片）
- 全文搜索（倒排索引）
- 语义搜索（向量搜索）
- 懒加载渲染（按可视区域加载）
- 文档版本控制（chunk diff）
- 文档后台系统（编辑、发布、管理）
- 前端渲染完全 VitePress 化（主题与布局可继承）
- 后端文档 API（动态模式）
- 多用户系统（可扩展）
核心思想总结（最重要部分）
⭐ 核心概念：Chunk（分片）
所有文档都被拆成可管理的小块。
每个 chunk 是：
{
id: string,
docId: string,
type: "heading" | "paragraph" | "code" | "table",
order: number,
content: markdown_substring,
html: optional_cache,
tokens: [...],
embedding: optional_vector
}这意味着：
- ✔ diff 更快速
- ✔ 懒加载可做
- ✔ 搜索更精准
- ✔ 更新更轻量
- ✔ 可并发加载
⭐ 渲染器动态化
原本的：
createMarkdownRenderer(root)是用于构建阶段，但你希望：
- 在 运行时 调用它
- 根据请求实时渲染 Markdown → HTML
- 甚至可缓存到 Redis/DB
⭐ 文档以 Markdown 原文保存，不保存 HTML
好处：
- 体积小
- 修改更快
- 可以版本控制
- 可以直接导入/导出
- 可重复渲染多主题
架构设计
架构图（文本式）
┌────────────────────────────┐
│ VitePress Pro │
│ (前端渲染系统) │
│ - 可视区域懒加载渲染 │
│ - 分片动态加载 │
│ - 主题：基于 VitePress │
└──────────┬─────────────────┘
▼
┌────────────────────────────┐
│ Document API │
│ - GET /doc/:id │
│ - GET /doc/:id/chunks │
│ - GET /chunk/:chunkId │
│ - POST /doc │
└──────────┬─────────────────┘
▼
┌────────────────────────────┐
│ 文档管理后台 │
│ - 编辑器（在线 MD 编辑） │
│ - 发布/预览/版本回退 │
│ - 搜索、分类 │
└──────────┬─────────────────┘
▼
┌────────────────────────────┐
│ 文档存储数据库（DB） │
│ Markdown 原文 + Chunk 表 │
│ 索引表 + 版本表 + 用户表 │
└──────────┬─────────────────┘
▼
┌────────────────────────────┐
│ AI/搜索系统（可选） │
│ - 向量搜索 │
│ - 全文搜索 │
└────────────────────────────┘数据库设计（初版）
以 PostgreSQL 为例。
文档表
documents
---------
id (pk)
title
createdAt
updatedAt
authorId分片表（最核心）
chunks
---------
id (pk)
docId (fk)
order (int)
type (enum)
markdown (text)
html (text, optional cache)
hash (text)
tokens (tsvector) -- 用于全文搜索
embedding (vector) -- 用于语义搜索（可选）版本表
versions
---------
id
docId
createdAt
changes: jsonb -- {chunkId: {oldHash, newHash}}文档分片设计（Chunking）
支持两种策略：
① 标题分片（结构化）
根据：
# / ## / ###切成层级结构。
用于：
- 目录
- 页面定位
- 层次化展示
② 智能分片（均匀）
按：
- tokens 数量（200~500）
- 段落边界
- 句子边界
切分。
用于：
- 搜索
- 懒加载
- diff/版本
⭐ 推荐混合模式：
一级结构：按标题分片
标题内部：按智能分片懒加载渲染（可视区域渲染）
前端使用：
IntersectionObserver在 chunk 可见时加载并渲染。
伪代码：
<div v-for="chunk in chunks" v-intersect="load(chunk)">
<ChunkRenderer :chunk="chunk" />
</div>渲染流程：
1. 请求 chunk markdown
2. 调用 createMarkdownRenderer.render()
3. 生成 html
4. 挂载 Vue 组件缓存策略：
- 内存缓存（tab 内）
- IndexedDB 缓存
- 服务端缓存（Redis）
版本控制设计（Diff）
采用 chunk diff。
流程：
旧文档分片 → 对比 hash → 找到变化的 chunk → 对变化部分执行文本 diff → 保存增量版本。细粒度 diff 使用：
- diff-match-patch
- 或 jsdiff
这样你可以：
- 高效版本回退
- 快速找出改动点
- 不保存整个文档
搜索体系设计
支持两种搜索：
全文搜索（倒排索引）
基于 PostgreSQL：
tsvector(chunk.markdown)查询：
SELECT * FROM chunks WHERE tokens @@ plainto_tsquery('keyword')优势：
- 高性能
- 支持高亮
- 原生
语义搜索（embedding）
embedding vector 存入：
pgvector查询：
SELECT * FROM chunks ORDER BY embedding <-> $query LIMIT 10;用途：
- 智能推荐
- 内容关联
- 文档问答
后台管理系统（CMS）
支持功能：
- 文档列表
- 在线 Markdown 编辑器
- 草稿与发布
- 文档版本查看（diff 视图）
- 文档导入/导出
- 用户权限
技术栈：
- Vue3 + Vite + Naive UI（轻量）
- 你的 Mist.js 也可以内嵌作为一个子组件（非常酷）
动态渲染器（Runtime Renderer）
核心思想：
不用构建，直接用 Node 版 VitePress 渲染器在运行时渲染 MD。
依赖：
import { createMarkdownRenderer } from 'vitepress'你需要：
- 把这套插件链迁移到运行时
- 移除只依赖构建时的逻辑
- 删除 Rollup-only 的代码
- 保留 Markdown → HTML → Vue SFC 的过程
你可以把整个渲染器封装成一个：
@vitepress-pro/renderer技术挑战与解决建议
大文档滚动性能
解决：
- chunk 级渲染
- 虚拟列表（Virtual Scroller）
- 预加载相邻 chunk
SSR？
可选：
- 动态渲染 SSR（像 Nuxt 内容模块）
- 或纯 SPA（更轻）
SEO
动态 HTML 可用：
- serverless SSR
- 或静态预渲染（只渲染第一页）
多主题切换
每个 chunk 的 HTML 可反复解析 → 支持主题动态切换
项目路线图（Roadmap）
阶段 1：最小可用版（MVP）
- 动态渲染器
- 文档 CRUD
- 文档分片（标题 + 智能）
- API 服务
- 前端渲染（无懒加载）
阶段 2：进阶功能
- 懒加载渲染
- 缓存
- 搜索（倒排）
- Markdown 编辑器
- 版本控制（chunk diff）
阶段 3：高级功能
- 语义搜索（向量）
- 多主题系统（多皮肤）
- 多用户权限
- 文档同步（Git-like）
阶段 4：产品化
- 网站托管服务
- 插件系统（像 VitePress plugin）
- 模板系统
- AI 文档分析
- 文档生成 API（AI → Markdown）
未来想法（可成为项目支线）
- 智能文档分片算法（可成为独立库）
- 文档 diff 引擎（类似 git diff，但更轻）
- Markdown 渲染器模块化（一个纯运行时的 VitePress Renderer）
- 文档搜索引擎（可开放 API）
- 动态知识库（像 Notion 或 Obsidian）
总结：VitePress Pro 是一项“大工程”
它不是一个简单的项目，而是：
- 一个框架
- 一个 CMS
- 一个搜索引擎
- 一个动态渲染器
- 一个版本控制系统
- 一个专业级知识库平台
而这些能力，对你未来技术成长也有巨大推动。
- 完整数据库 schema（SQL）
- 完整 API 文档
- 分片算法的伪代码
- 动态渲染器的代码框架
- 管理后台的 UI 图
- 项目 Monorepo 结构