站点约定
Plume 优先 · 少改 CSS
本站基于 VuePress 2 + vuepress-theme-plume。展示、布局、嵌入优先用主题指南与配置，不自造等价 UI。
| 需求 | 用法 |
|---|---|
| 相册瀑布流 | ::: card-masonry |
| 艺人图卡 | <ImageCard> + VPCardGrid |
| 网站链接 / 音乐曲目 | <LinkCard> + VPCardGrid（仅此两处） |
| 应用访问 / 快捷入口 | Markdown 链接列表 |
| 站点导航 | Markmap |
| 表格全宽 | ::: table full-width |
| 文章标题 | frontmatter title；正文从 ## 起 |
| 视频 | @[bilibili] |
| 首页 | doc-hero + features |
| 卡片列数 | <VPCardGrid :cols="{ sm:1, md:2, lg:3 }"> |
自定义样式由 client.ts 引入 docs/.vuepress/styles/ 下的 brand / home-hero / dark-button（只覆盖 CSS 变量）；不要在 CSS 里 @import 同目录文件。不用 CSS 改布局或藏标题。
正文忌套话
正文只写给读者看的内容，不写实现说明。
不要写：左右栏提示、主题组件名、对齐某某站、如何启用某 markdown 开关等。约定写在本页或仓库规则里即可。交叉链接（如「见环境说明」）可以保留。
信息架构
顶栏顺序（尽量四字）：
- 站点导航
- 运行环境
- 应用访问
- 快捷入口
- 网站链接
- 设备资产
- 版本号 → 更新日志 / 本页
音乐、相册、关于不进顶栏。页面标题与顶栏文案一致。
知识库保持一级目录，不大挪路径。门户在 docs/portal/，对外用短路径（如 /map/）。
架构图放哪里
用本站已启用的 Mermaid 即可，不另装引擎，也不为架构单独加顶栏。拓扑 / 部署 / 模块图统一用 ```mermaid + flowchart，并在图内写 theme: base 与黑白灰 themeVariables（与 家庭网络 同款）；勿用 ```architecture（易渲染失败）。图会随正文宽度缩放。
| 类型 | 位置 | 说明 |
|---|---|---|
| 家庭工作室网络拓扑 | 家庭网络 | 与 设备资产、快捷入口 交叉链接 |
| 项目部署 / 运行依赖 | 运行环境 下对应项目页 | 如芋道、WordPress 环境页的「部署架构」 |
| 项目模块 / 分层 | 知识库开发文档对应介绍页 | 如 芋道 |
| 其它流程 / 时序 | 跟所属文章同页或同目录 | 勿集中堆成「架构图库」 |
静态资源（双轨）
| 类型 | 放哪 | 怎么写 |
|---|---|---|
| Logo、门户图标、音乐/相册封面等跨页资源 | docs/.vuepress/public/（勿用 docs/public） | 绝对路径 /music/…、/portal/… |
| 单篇教程截图、配图 | 与 .md 同目录（或旁路 images/） | 必须 ./xxx.png（裸写 xxx.png 会导致 Vite 构建失败） |
- 网页用图建议单张 ≤ 500KB；封面可更严。
- PMP 等教材 PDF 暂保留并参与构建；日后若要减部署体积再单独迁出。
npm run docs:check会拦截：死链、缺资源、裸相对资源路径，并对过大图片告警。- 禁止写入真实凭据：文档示例用
db.example.com/<your-password>等占位；勿提交真实 JDBC、Redis、云密钥。若已误推，先改文档再轮换线上口令。
分支与发版
- 日常开发 / commit：只在
plume，不要在main上直接改。 - 发版顺序（固定，勿颠倒）：
npm run docs:check:build通过- 在
plume写 更新日志、升版本（如需）、提交并打 tagvX.Y.Z - 将
plume合并进main - 再
git push（推main与 tag；建议同时推plume）
- 线上以 main 为准：推送到
main后 GitHub Actions 先docs:check再构建部署到gh-pages。 - 可选：
git config core.hooksPath .githooks，push 时自动跑门禁（不能代替发版前的完整检查）。
更新日志：## vX.Y.Z + 按实际写新增 / 优化 / 修复（不必三项都有）；与 package.json version、GitHub tag 一致（tag 带 v 前缀）。
约定维护
可复用的约定变更时，同步更新本页与仓库 .cursor/rules/（助手规则与站点约定保持一致）。一次性踩坑写开发记忆即可，不必上本页。
本地开发
改顶栏、config.ts 的 markdown/plugins、permalink、collections，或新启用图表 / Bilibili / 表格等之后，硬刷新往往无效，需 npm run docs:clean-dev（Node ≥ 22.18）。
- 快速检查：
npm run docs:check - 对齐 CI / 发版前：
npm run docs:check:build