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 结构