用 VuePress 将 Vue.js 资源清单编译为带 PWA 的静态站点浏览体验

方案简介

本方案是一个基于 VuePress 的 Vue.js 资源清单站点。项目本身是一份「awesome things related to Vue.js」的精选清单，但并不满足于停留在 GitHub README 形式，而是明确表示「does not aim to replace the official Vue.js Awesome List but rather to provide a nicer experience when browsing the content」——即通过 VuePress 将 Markdown 内容编译成更易浏览的静态站点。它适合维护 awesome 清单、文档型开源项目、希望把 Markdown 内容发布为网站并托管到 GitHub Pages 的开发者。

亮点与能力

• 将 Markdown 清单内容自动编译为静态站点
• 开发模式本地服务器热更新，改 Markdown 即时反映到页面
• 生产构建输出 content/.vuepress/dist 目录，便于部署
• 内置 PWA 支持（@vuepress/plugin-pwa）
• 内置回到顶部插件（@vuepress/plugin-back-to-top）
• markdownlint 检查 Markdown 格式规范

组成与分工

• VuePress：核心静态站点生成器，编译 Markdown 并提供 dev 服务器
• @vuepress/plugin-pwa：为站点提供 PWA 能力
• @vuepress/plugin-back-to-top：提供回到顶部按钮
• markdownlint-cli：lint 脚本调用的 Markdown 格式检查器
• serve：本地预览构建产物的静态服务器
• GitHub Pages：站点部署目标（仓库自带 GitHub Pages 工作流）

前置要求

需要 Node.js 与 npm 环境。克隆仓库并安装依赖：

bash
git clone https://github.com/rmjordas/awesome-vue.git
cd awesome-vue
npm install

实施步骤

1. 克隆并安装依赖

bash
git clone https://github.com/rmjordas/awesome-vue.git
cd awesome-vue
npm install

2. 启动开发服务器

运行 dev 脚本编译内容并启动本地服务器：

bash
npm run dev

此脚本运行期间，对 Markdown 文件的任何修改都会自动更新到本地页面。

3. 构建生产版本

bash
npm run build

构建会在 content/.vuepress 下生成 dist 目录。

4. 本地预览构建产物

bash
npm install -g serve
serve content/.vuepress/dist

5. 部署

将 dist 目录部署到 GitHub Pages 即可（仓库配置了 GitHub Pages 工作流）。提交前可运行 lint 检查：

bash
npm run lint

使用与配置要点

日常贡献只需编辑 Markdown 清单文件，npm run dev 会实时刷新页面。可用脚本一览：

| Script | Description |
|---------|---------------------------------------------------------|
| dev | Compiles content and serves bundled code |
| build | Compiles content and other static assets for deployment |
| lint | Runs markdown linter to check lint errors |
| test | An alias for lint (runs lint script) |

贡献方式请参考仓库的 Contributing Guide。

注意事项与常见问题

• 项目采用 Unlicense，即完全无限制的公有领域授权：This is free and unencumbered software released into the public domain.
• 本项目定位是浏览体验增强版，不取代官方 Vue.js Awesome List。
• 构建产物路径固定为 content/.vuepress/dist。

优缺点

• ✓ Markdown 修改自动热更新
• ✓ 自带 PWA 与回顶插件
• ✕ 依赖 VuePress 1.x 较旧

出处

本方案挖掘自开源项目 rmjordas/awesome-vue，方案内容与实施命令均来自其 README 原文。