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