大约 4 分钟
我看了这个仓库:VuePress 2,大约 696 篇 Markdown、近 4000 张图片,没有 CI。整体看,内容很多,但工程化和维护能力跟不上内容量。下面按收益从高到低列出建议。
一、优先处理(维护成本和稳定性)
1. 图片太大,仓库已经膨胀
docs下的图片约 637MB(其中包括dist构建产物里的副本),git 打包后有 360MB,所以 clone 和部署都很慢。- 建议把图片统一压缩或转成 WebP,可以用
sharp、squoosh或imagemin批量处理。有 30 张图超过 1MB,像vue2_api.gif这种 GIF 可以改成 MP4 或 WebP 动图。 - 长期可以改用图床或对象存储(OSS/COS 加 CDN),也可以用 Git LFS 管理图片。
2. 依赖版本混乱,还有很多装了没用的包
vuepress和@vuepress/bundler-vite停在rc.18,插件却到了rc.57到rc.74。VuePress 2 的 rc 版本之间要求核心和插件版本严格匹配,这样混用容易出现隐性报错。可以先运行已经配置好的docs:update-package统一升级。- 下面这些包装了,但
config.ts里没有使用:plugin-blog、plugin-copyright、plugin-docsearch、plugin-pwa、plugin-watermark、plugin-markdown-container、plugin-back-to-top,还有dependencies里的三个 markdown-it toc 包。建议要么启用,要么删掉。 - 仓库里同时有
package-lock.json和yarn.lock,只保留一个包管理器。 package.json里的name: "ai-for-everyone"和description还是模板默认值,可以改掉。
3. 侧边栏是手写的,维护负担重
- 光
zh_detail.ts就有 1080 行,zh.ts还有 507 行。每加一篇文章都要手动登记,很容易漏,待补充.txt里记的"导航有问题、修正路由"就是这类问题。 - 建议按目录结构自动生成侧边栏:写个小脚本读每篇文章的 frontmatter(
title、order)生成配置,或者换成支持sidebar: "structure"的vuepress-theme-hope。
4. 清理没用的配置和文件
docs/en只有 1 篇文章,但英文的 nav/sidebar 配置有 300 多行。要么认真做英文版,要么删掉。.gitignore只写了node_modules,建议补上docs/.vuepress/.temp、.cache、dist、.specstory等。client.ts是空的,只有一句注释,可以删掉,或者留给后面的定制功能用。- 通知栏里"github地址"链到
cpp-notes,但当前仓库的 remote 是stibel,确认一下链接对不对。
二、提升内容质量和可发现性
5. 补齐 frontmatter
- 696 篇文章里只有 2 篇写了 frontmatter,几乎没有
date、tags、category、description。 - 没有这些信息,就做不了按标签/分类浏览、最新文章列表、归档页,SEO 插件也只能自动截取正文当摘要。
- 建议写个脚本批量补上
title和date(可以取 git 首次提交时间),再逐步补tags。
6. 用上博客能力
plugin-blog已经装了,配合 frontmatter 可以做出"最新文章 / 标签 / 分类 / 时间线"页面。知识博客的回访用户最需要这个。- 首页可以加"最近更新"和"推荐阅读",现在首页只有三个口号式的 feature。
7. 搜索升级
- 内置的
searchPlugin只搜标题和小标题,对 700 篇文章的站点不够用。 - 可以换成已安装的
docsearch(Algolia 免费申请),或者用slimsearch做本地全文搜索。
8. SEO 补全
- 加
@vuepress/plugin-sitemap(注意不要和 seo 插件混淆),然后提交到百度和 Google 站长平台。 - 每篇文章配上
description,效果会明显变好。
9. 处理未完成的内容
- 有 32 个文件含 TODO 或"待补充",55 个文件不到 300 字节,基本是空壳页。
- 建议给这类页面统一加一个"施工中"提示,或者先不放进导航,免得读者点进去失望。
三、增强互动和体验
10. 加评论系统:notice 写的是"期望聆听大家的意见和反馈",但站内没有反馈入口。可以接 Giscus(基于 GitHub Discussions,免费、无广告)。
11. 加"在 GitHub 上编辑此页":给默认主题配上 repo、docsRepo、docsDir: 'docs',读者可以直接提 PR 纠错。
12. 阅读体验:可以补上代码块复制按钮(plugin-copy-code)、阅读时间估计、文章页的上一篇/下一篇。图片已经接了 photoSwipe 预览,这一点不错。
四、工程化
13. 加 CI/CD:现在没有 .github/workflows。建议加一个 GitHub Actions,push 时自动构建部署,同时做两项检查:
- 死链检查,比如
lychee或markdown-link-check,这对路由经常调整的站点很关键; - Markdown 格式检查,比如
markdownlint。
14. 内容和工具分开:tools/translate 下的翻译脚本和输出文件跟博客站点关系不大,可以挪到单独的仓库或目录。
如果只做三件事,我建议依次是:统一依赖版本、压缩图片、按目录自动生成侧边栏。它们分别解决构建稳定性、仓库体积和日常维护成本,之后的博客化和搜索改进做起来也更顺。需要的话,我可以从其中任何一项开始动手。
