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 | Obsidian 笔记(打 #网站发布 标签) |
脚本(private_hexo/tools/obsidian_to_hexo.py,Python3 零依赖)做五件事:
- 筛选:默认只扫描库里的
Projects/影响力/网站文章目录(可用--source-dir改),命中规则是「文件名带 [网站] / [网址] 前缀」或「打了 #网站发布 标签」 - 生成元数据:从 front-matter 读 title/date/categories/tags,缺的用文件名、文件修改时间、默认值补齐;复用已存在文章的文件名做 slug,避免 URL 变更
- 转换正文:去掉注释标记和块引用 id,wiki 双链降级为纯文本
- 搬运图片:把 Obsidian 的图片嵌入找出原图复制到 Hexo 的 source/downloads/images/obsidian,并改写为标准图片路径(按内容哈希命名,避免冲突)
- 记录状态:用
.sync_state.json记住「哪篇文章由哪篇笔记生成」,后续只更新变化的,源笔记不再命中时网站文章保留不动(只报告不删除)
设计上默认 dry-run:不加 --apply 只预览不写文件,安全优先。已存在但未被纳管的同名文章默认跳过,需 --adopt 才接管,避免误覆盖。
怎么使用
第一步:标记要发布的笔记
在 Obsidian 笔记里任意位置写一行:
1 | #网站发布 |
(本文就是打了这个标签的 demo,已成功同步为网站文章)
第二步:运行脚本
在 private_hexo 目录下:
1 | # 预览:看看会同步哪些笔记、生成什么文件名 |
常用参数
| 参数 | 作用 |
|---|---|
--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
