Obsidian 和 Hexo 博客平台联动

#网站发布

目标

把 Obsidian 库里的一部分笔记,作为 Hexo 网站文章的原始文件,实现「在 Obsidian 里写,一键同步到网站」。

核心原则:单向同步,Obsidian 是唯一事实源

这套方案是单向的,不是双向的。Obsidian 是唯一事实源(single source of truth),Hexo 的 source/_posts 是生成产物。

这个原则不可动摇,原因是:

  • 两边都允许改,最后一定会冲突。同一篇文章在两处各自演化,没有可靠的自动合并办法,最终必然出现内容分歧、难以判断哪个才是正确版本。
  • 在网站仓库里直接改的文章,下次同步会被 Obsidian 版本覆盖。因为脚本的每一次运行都以 Obsidian 笔记为准重新生成目标文件,Hexo 侧的手动修改不会被保留,也不会回流。

因此实际操作上必须遵守:

  • 改内容,只改 Obsidian 笔记,改完重新跑同步脚本
  • Hexo 的 source/_posts 视为只读产物,不要直接在里面编辑文章;如果要改某篇网站文章,回到对应的 Obsidian 笔记改,再同步
  • 如果哪天确实需要在网站上做临时修改,也要想清楚它会在下次同步时丢失

脚本本身也按这个原则设计:状态文件 .sync_state.json 只记录「哪篇文章由哪篇笔记生成」,用于判断更新;从不做 Hexo → Obsidian 的反向写入。

为什么不能直接软链接

两边的 Markdown 并不兼容:

维度 Obsidian Hexo 要求
元数据 大多没有,或不规范 必须有 YAML front-matter(title/date/tags/categories)
内部链接 双方括号 wiki 语法 标准 Markdown 链接语法
图片 感叹号 + 双方括号嵌入 标准图片语法 + 图片放进 source
文件名 中文 英文 slug(影响 URL)

所以中间必须有一层「转换」,这就是同步脚本干的事。

实现方式

架构是一条单向流水线:

1
2
3
4
5
6
7
Obsidian 笔记(打 #网站发布 标签)
↓
同步脚本 obsidian_to_hexo.py(v2)
↓ 生成 front-matter / 转换链接和图片 / 写入
Hexo source/_posts/*.md
↓ hexo g -d
GitHub Pages 上线

脚本(private_hexo/tools/obsidian_to_hexo.py,Python3 零依赖)做五件事:

  1. 筛选:默认只扫描库里的 Projects/影响力/网站文章 目录(可用 --source-dir 改),命中规则是「文件名带 [网站] / [网址] 前缀」或「打了 #网站发布 标签」
  2. 生成元数据:从 front-matter 读 title/date/categories/tags,缺的用文件名、文件修改时间、默认值补齐;复用已存在文章的文件名做 slug,避免 URL 变更
  3. 转换正文:去掉注释标记和块引用 id,wiki 双链降级为纯文本
  4. 搬运图片:把 Obsidian 的图片嵌入找出原图复制到 Hexo 的 source/downloads/images/obsidian,并改写为标准图片路径(按内容哈希命名,避免冲突)
  5. 记录状态:用 .sync_state.json 记住「哪篇文章由哪篇笔记生成」,后续只更新变化的,源笔记不再命中时网站文章保留不动(只报告不删除)

设计上默认 dry-run:不加 --apply 只预览不写文件,安全优先。已存在但未被纳管的同名文章默认跳过,需 --adopt 才接管,避免误覆盖。

怎么使用

第一步:标记要发布的笔记

在 Obsidian 笔记里任意位置写一行:

1
#网站发布

(本文就是打了这个标签的 demo,已成功同步为网站文章)

第二步:运行脚本

在 private_hexo 目录下:

1
2
3
4
5
# 预览:看看会同步哪些笔记、生成什么文件名
python3 tools/obsidian_to_hexo.py

# 确认无误后,实际写入
python3 tools/obsidian_to_hexo.py --apply

常用参数

参数 作用
--source-dir 目录 只扫描库里这些目录,可重复传(默认「Projects / 影响力 / 网站文章」)
--prefix 前缀 文件名含该前缀才同步,可重复(默认 [网站]、[网址])
--tag 标签名 换发布标签,默认 网站发布
--exclude-dir 目录 / --exclude-name 名称 排除目录或文件名关键词
--adopt 接管已存在但内容不同的同名文章(覆盖)
--no-update 不更新已纳管的文章
--keep-wikilink / --keep-boilerplate 保留双链原样 / 保留样板提示行
--images-dir / --state 自定义图片目录和状态文件路径

如果只想靠标签筛选、不希望文件名前缀规则生效(例如做单篇测试),可以传一个不会匹配任何文件的前缀:

1
python3 tools/obsidian_to_hexo.py --prefix "__nomatch__" --apply

这里的 __nomatch__ 只是一个占位值,作用是把默认的前缀规则「架空」,从而只保留 #网站发布 标签筛选。

第三步:部署上线

脚本只写文件,不会自动部署。生成完成后:

1
hexo clean && hexo g -d

当前限制

  • 单向(设计如此):只做 Obsidian → Hexo,网站上的改动不回流、会在下次同步时被覆盖。详见上文「核心原则」。
  • 图片依赖原始文件存在:图片嵌入若库里找不到同名原图,会退化成占位路径并给出警告,需手动补图
  • 标签语法:示例里的 wiki 图片 / 双链写法若出现在正文,会被脚本当真实引用处理,写示例时注意用文字描述

相关文件

  • 脚本:hexo_dir/tools/obsidian_to_hexo.py
  • 说明:hexo_dir/tools/README-obsidian-sync.md