VitePress 完整通俗讲解（结合你之前 MineAdmin 文档场景）

1. 一句话定义

VitePress 是 Vue 官方出品、基于 Vite + Vue3 的静态站点生成工具（SSG），专门用来快速搭建项目文档、技术手册、博客网站，MineAdmin 的全套文档就是用它做的。

简单拆解名字：

  • Vite：新一代前端构建工具，启动、热更新极快；
  • Press：文档/站点生成（前身 VuePress）。

2. 核心原理（MineAdmin 文档就是这套流程）

  1. 你写一堆 .md Markdown 文件（MineAdmin 文档仓库里全是 md）；
  2. VitePress 读取 md，自动生成侧边栏、导航、搜索、代码高亮；
  3. 本地运行 yarn dev 开启开发预览，改 md 页面秒刷新；
  4. 打包 yarn build 输出纯静态 HTML/CSS/JS，丢到服务器就能在线访问（doc.mineadmin.com 就是打包后的产物）。

3. 关键特性（为什么几乎所有前端开源项目都用它做文档）

  1. 极致开发速度
    依托 Vite，启动服务器几乎瞬间，修改文档保存 <100ms 页面自动刷新，不用等待打包，写文档体验极好。

  2. Markdown 增强 + 支持 Vue 组件

    • 原生支持代码块高亮、折叠代码、提示框、目录、多语言；
    • md 文件里可以直接写 Vue 组件，文档里能嵌入可交互演示组件（比如 MineAdmin 展示表单、表格组件示例）。
  3. 自带成熟文档主题
    默认模板自带：顶部导航、侧边目录、全局搜索、暗黑模式、版本切换、页内锚点，开箱即用，不用自己写页面布局。

  4. 性能兼顾首屏与跳转

    • 首次打开：预渲染静态 HTML，加载速度快；
    • 页面间切换：自动转成单页应用 SPA，无刷新跳转，丝滑。
  5. 部署零门槛
    build 完只有静态文件，可部署 Nginx、Gitee Pages、GitHub Pages、云存储，不需要后端服务。

4. 和 VuePress 的关系（历史）

  • VuePress 1.x：老一代，Vue2 + Webpack，启动慢、热更新卡顿；
  • VitePress：Vue 团队重做的升级版，Vue3 + Vite，性能全面碾压，现在官方主推，VuePress 基本不再维护。

5. 对应你 MineAdmin 文档的实操逻辑

MineAdmin 文档仓库 mineadmin-doc 就是标准 VitePress 项目：

  1. 目录下全是 Markdown 教程文档；
  2. 配置文件控制导航、侧边栏、版本切换；
  3. yarn dev 本地跑旧版/新版文档；
  4. 打包后上传，对外访问 doc.mineadmin.com。

6. 适用场景

  • 开源项目技术文档（Vue、Vite、MineAdmin、Element Plus 全部在用）
  • 私人技术笔记、知识库、博客
  • 内部系统接口手册、开发规范文档

7. 极简使用流程（看懂即可本地跑 MineAdmin 旧文档）

# 1. 拉取 MineAdmin 文档仓库
git clone https://gitee.com/mineadmin/mineadmin-doc.git
cd mineadmin-doc

# 2. 安装 VitePress 依赖
yarn install

# 3. 本地启动文档站点
yarn dev

# 4. 打包静态文件用于线上部署
yarn build

访问 http://localhost:5173 就能离线查看完整旧版 MineAdmin 前端文档。

版权属于：Joyber

本文链接：https://blog.qqvbc.com/default/1493.html

转载时须注明出处及本声明

标签: none

添加新评论