我用 VitePress 搭建了一个长期维护的个人知识文档站

我用 VitePress 搭建了一个长期维护的个人知识文档站

学习 Java 后端的过程中，我积累了大量课程笔记、项目记录和问题解决方案。最开始，这些内容分散在不同文件夹里，需要时很难快速找到，也不方便持续维护。

于是，我使用 VitePress 搭建了一个个人知识文档站：jackson凌の知识文档站。

• 在线访问：https://jacksonling.cn/
• GitHub：https://github.com/jackson-ling/vitepress

为什么选择 VitePress？

对个人知识库来说，我最看重三点：使用 Markdown 写作、构建速度快、能够自由定制界面。

VitePress 正好满足这些需求。文章本身仍然是普通 Markdown 文件，可以直接通过 Git 管理；站点则可以借助 Vue 组件和主题扩展，逐步完善导航、搜索与阅读体验。

我做了哪些定制？

这个站点并不是简单套用默认主题。目前已经实现：

• 自定义动态首页，包括 Loader、滚动场景和移动端交互；
• 使用 Pagefind 建立静态全文索引，并优化中文搜索；
• 自动生成部分侧边栏，减少新增文章时的重复配置；
• 阅读进度、回到顶部和当前目录高亮；
• 使用 PhotoSwipe 实现正文图片缩放与拖拽预览；
• 优化亮暗主题首屏显示，减少页面加载时的背景闪烁；
• 使用 GitHub Actions 自动构建并部署到 GitHub Pages。

内容目前主要围绕 Java、算法、Spring 生态、数据库与中间件、项目实践、Python 和 AI 应用展开。它首先是我自己的学习档案，也希望能为正在整理知识体系的同学提供一些参考。

本地运行

项目使用 Node.js 18.20.4 和 npm：

git clone https://github.com/jackson-ling/vitepress.git
cd vitepress
npm ci
npm run docs:dev

启动后访问 http://localhost:5173 即可查看。

生产构建命令为：

npm run docs:build

构建过程会同时生成 Pagefind 搜索索引，产物位于 .vitepress/dist。

写在最后

搭建知识库并不难，真正困难的是长期整理和持续更新。我希望这个项目能让我减少重复查找，把学习过的知识逐渐连接起来，而不是让笔记写完后就被遗忘。

如果你也在使用 VitePress 搭建个人文档站，可以访问我的网站看看实际效果。项目中的首页动效、中文搜索、图片预览和主题配置也都可以在 GitHub 中查看。

在线文档： https://jacksonling.cn/

项目源码： https://github.com/jackson-ling/vitepress

如果这个项目对你有帮助，欢迎在 GitHub 点一个 Star，也欢迎交流改进建议。