Skill · 本地预览 + 部署前自检

何时用：想在 push 前看一眼最终效果；或者想看看 deploy workflow 报的 warning 都什么意思。

解决什么：把"本地预览"和"导出审计"两件事说清——一个解决"我写出来到底长啥样"，一个解决"我写的东西有没有死链"。

一、本地预览（gobog-obsidian 插件）

前置条件：本地编了 gobog 二进制。

git clone https://github.com/sbraveyoung/gobog ~/code/gobog
cd ~/code/gobog
make build       # 产出 ./gobog

配置插件：

• 设置 → Gobog Sync → Local preview
  • gobog binary path = /home/<you>/code/gobog/gobog
  • theme path = 留空（默认 <bin-dir>/themes/minimal）

用：命令面板 → Gobog Sync: Preview blog locally

它会：

1. 把当前 vault 的 Blog/ 目录作为 source；
2. 写一个临时 gobog.toml 到 tmpdir；
3. gobog -export 到 <vault>/.obsidian/plugins/gobog-obsidian/preview/；
4. 用 file:// URL 把渲染结果在系统默认浏览器里打开。

贴心：如果你当前打开的是某篇文章（且在 blog 文件夹下），它会直接跳到这篇文章的渲染页，不需要你从首页往里点。

二、部署前自检（github.io 的 deploy workflow）

scripts/check-export.sh 在每次 deploy 跑 gobog -export 之后自动跑一遍。三类警告：

1. dead internal link

/post/X 或 /image/X 在 HTML 里出现，但导出树里没那个文件。

::warning::dead internal link: /post/cf4cc8e2/e66fb74

常见原因：

• 文章里硬写了 /post/<旧 id>，那篇文章已经被删了 / 改了 url。
• 老 wikilink 指向已不存在的笔记。
• 手敲 markdown 链接的时候 typo 了。

修法：在 vault 里 grep 一下那个 URL，找到引用它的 .md，要么改对，要么删掉。

2. orphan resource

image/X 文件存在，但没有任何 HTML 引用它。

::warning::orphan resource: image/旧截图.png

常见原因：

• 某篇文章删了，引用的图片留下了。
• 早期上传过但从未引用的素材。

修法：要么找一篇文章把它用起来，要么 git rm。两种都行——警告不阻断发布，留着只是为了让你知道你在多送几 KB 字节。

3. suspicious URL

HTML 里出现了 file:///、localhost、127.0.0.1 这种只在你本地有意义的 URL。

::warning::suspicious URL leaked into HTML: file:///D:/temp/...

常见原因：从 Typora / 别的本地编辑器复制粘贴时把本地路径带进来了。

修法：在 vault 里搜那个 URL，替换成线上路径或者改成 /image/...。

注意：<!-- ... --> HTML 注释里的可疑 URL 不会触发警告（脚本是 comment-aware 的）。

三、本地手动跑自检

不想等 deploy？本地直接跑：

# 先用插件预览一遍生成 _dist
# 然后：
bash ~/code/sbraveyoung.github.io/scripts/check-export.sh \
  ~/<vault>/.obsidian/plugins/gobog-obsidian/preview

输出格式跟 GH Actions 里一模一样，只不过没了 ::warning:: 前缀的 Actions 渲染。

四、把警告升级成 fail（可选）

scripts/check-export.sh 默认只 warn。如果你想让 dead link / orphan 直接阻断 deploy：在 github.io 的 deploy.yml 里把 CHECK_EXPORT_FATAL 设成 '1'：

- name: Sanity check rendered output
  env:
    CHECK_EXPORT_FATAL: '1'   # 改这里
  run: bash scripts/check-export.sh _dist

我的建议是保持默认 warn——少数派审稿员的角色让自动化干，最终决定权留给自己。