博客更新说明 · Zwing's blog

1 为啥更新

有新则有旧。25 年 11 月前后，刚上大二的我在好友 Ferne 的推荐下，使用 Hexo 开箱即用地搭建起之前的那个博客。

而最近半年我几乎都是使用 VS Code 做笔记，在其中使用插件 Markdown Preview Enhanced（MPE）渲染预览。当我想把笔记搬运至博客时发现 MPE 的某些样式在之前的博客主题下无法渲染，在其上修改构建脚本的效果不佳，故想到不如自己推倒重做以完全自定义化。

适逢 deepseek-v4-flash 正式版发布，且还未正式涨价（梁圣你这斩杀线怎么这么快就沦陷了…），那还说啥了，直接火力全开（最终消费仅约￥10）

2 更新了啥

“站在巨人的肩膀上”

文章页参考 MPE，非文章页参考 Hexo 主题 redefine

支持 MPE 风格的提示框：不同类型颜色的提示框，如上面的这句引用（这人喜欢花花绿绿的东西）
支持荧光笔高亮：如现在看到的这句话
支持裸 HTML 插入：如一些异常复杂和美观的表格
支持 PlantUML 图：但实际上使用场景不多，只是为了更方便吧
支持更多的页面显示背景图：文章页的为可选，阅读才是重点（
支持图片压缩后上传展示：实则对读者透明，只是方便我本人部署…

当然还有很多其他细节的改动，在这里只补充另外两点（~~为什么没做~~）：

缩放：Ctrl + 鼠标滚轮 可缩放页面
检索：Ctrl + F 可检索页面内容

3 写给自己看的

各位看官到此可以止步了（也感谢你看到这里），下面的内容只是~~防止我自己太久没更新而忘记~~这个博客的写作样式、架构与部署方式等的说明。

3.1 文章样式

文章放在 source/_posts/（独立页面在 source/_pages/），Markdown 头部需带 front matter：

字段	说明
`title` / `tags` / `categories` / `description`	必填，description 显示在首页卡片与搜索索引
`date` / `updated`	可省略，自动从 git 历史取：首次提交时间 = 创建，最后提交时间 = 更新（均含时分秒）；显式写了以手写为准
`priority`	可选，int 置顶权重，主页按它降序排；>0 时卡片显示「置顶」标识
`cover`	可选，根路径封面图，显示在首页卡片顶部与文章页标题上方

正文支持 MPE 风格的扩展语法：

==文本==：荧光笔高亮
> [!note] 标题：提示框，共 9 种——note（蓝）/ info（青）/ tip（绿）/ success（绿）/ question（紫）/ warning（橙）/ example（青）/ quote（灰）/ important（红），另有 bug / fail 两种红色变体
```plantuml 代码块：构建时本地渲染为 SVG（根目录需有 plantuml.jar，没有则降级显示源码块）
$公式$ / $$公式$$：MathJax 数学公式，本地 tex-svg.js 渲染，无 CDN 依赖
```mermaid 代码块：Mermaid 图，客户端渲染，跟随明暗主题

图片规则：引用必须根路径 + .webp（/assets/img/posts/<slug>/<文件名>.webp）——文章页在 /posts/ 下，相对路径会 404。原图先经 node scripts/optimize-img.js 压缩再进仓库（图形 / 截图 WebP 无损、照片有损 q80、超 1600px 自动缩放），不要直接丢原 PNG（Pages 有 1GB 软上限，git 不压缩二进制）。

已知 Bug

双美元符公式块在与上文未空行的情况下，渲染时会被当作行内公式，导致换行失效。解决方法：公式块前后各空一行。

3.2 架构

无框架：markdown-it + 手写 Node 脚本，样式参考 MPE 与 redefine 主题。关键目录：

source/_posts/  文章（.md）
source/_pages/  独立页面（.md，如关于页）
assets/         静态资源（CSS/JS/图片）
scripts/        构建与工具脚本
config.json     站点配置（站点名、base 路径、社交链接等）
dist/           构建产物（git 忽略）

构建流程（npm run build → scripts/build.js）：

读 source/_posts/ 与 source/_pages/ 的全部 Markdown；
md.js 用 markdown-it + 插件渲染正文（提示框 / 高亮 / PlantUML / MathJax / 图片懒加载）；
templates.js 拼出各页 HTML（首页分页、文章页、标签 / 分类 / 归档、关于、404），页面布局都在这改；
输出到 dist/，资源 URL 追加 ?v=<构建时间戳> 版本号（绕开 GitHub Pages 的 10 分钟缓存）。

各脚本职责：build.js 主流程与分页；dev.js 本地开发（端口 4000，监听 source/、assets/、config.json，改 scripts/ 需重启）；plantuml.js 渲染 PlantUML；optimize-img.js 图片压缩；deploy-pages.js 部署。

3.3 部署

本地构建 + 推送 gh-pages 分支，不用 GitHub Actions（其部署步骤曾卡在 deployment_in_progress）：

npm run deploy:pages   # 构建 → 同步 gh-pages 分支 → 推送，一条命令

产物提交在 gh-pages 分支（孤儿分支，与 main 无历史关联），worktree 放在仓库外同级目录 ../myBlog-gh-pages，增量提交推送；
首次部署自动创建分支与 worktree；网页端一次性设置：Settings → Pages → Source 选 Deploy from a branch → gh-pages / (root)；
源码备份照旧走 main 分支：git add -A && git commit && git push，与部署互不影响；
部署后 GitHub Pages 约 1-2 分钟生效。

常用命令：

npm run dev                          # 本地开发（端口 4000）
npm run build                        # 构建 dist/
npm run optimize-img -- <源目录> <slug>   # 博文图片压缩
npm run deploy:pages                 # 构建 + 部署