📝 Obsidian 发布到 Hexo 工作流

✨ 目标很简单：平时继续在 Obsidian 写笔记，需要发布时，一键导出成 Hexo 能直接使用的文章。

🧠 推荐方案

我建议你走这条路：

  1. Obsidian 作为主写作端
  2. Hexo 作为展示端
  3. 用 frontmatter 控制是否发布、slug、分包、封面图
  4. 用脚本把笔记转换到 Hexo 的 source/_posts/<分类包>/

这条路的好处：

  • 日常写笔记不受影响
  • 不需要在 Hexo 和 Obsidian 里重复维护两份内容
  • 可以批量同步所有 publish: true 的笔记
  • 可以先 dry-run 预览落盘位置，再真正发布

🧩 目录建议

你当前笔记库里已经新增了一个发布目录：

  • hexo-publish/
  • hexo-publish/assets/covers/
  • hexo-publish/publish-note.mjs
  • hexo-publish/config.example.json

当前有两份常用配置：

  • hexo-publish/config.local.json：导出到 vault 内的测试目录
  • hexo-publish/config.deploy.json：导出到 HEXO_ROOT/source/_posts

配置里的路径支持占位符，换电脑时不用改脚本：

1
2
3
4
5
{
  "vaultRoot": "${configDir}/..",
  "hexoRoot": "${env:HEXO_ROOT}",
  "hexoPostsDir": "${hexoRoot}/source/_posts"
}

常用占位符：

  • ${configDir}：当前配置文件所在目录
  • ${cwd}：执行命令时所在目录
  • ${home}：当前用户主目录
  • ${env:HEXO_ROOT}：读取环境变量

✍️ 笔记怎么写

建议每篇准备发布的笔记都加上这些属性：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
title: Git 与 GitHub SSH 指南
publish: true
slug: git-github-ssh-guide
package: 技术笔记/开发工具
note_type: 工具类
date: 2026-06-24T10:00:00+08:00
updated: 2026-06-24T10:00:00+08:00
tags:
  - Git
  - GitHub
  - SSH
categories:
  - 开发工具
cover: hexo-publish/assets/covers/cover-git-terminal.png
description: 一篇够用的 Git、GitHub 和 SSH 上手笔记。
---

核心字段说明：

  • publish: 是否允许导出
  • slug: Hexo 文章链接名
  • package: 文章导出到 _posts 下的分包路径
  • note_type: 笔记类型，用来保留工具、速查、配置、流程、复盘这套习惯
  • cover: 文章封面图
  • description: 摘要描述

分包规则：

  • package 写了就优先使用，例如 技术笔记/开发工具
  • categories 第一项是 编程学习、大学课程、技术笔记、英语学习 时，直接按它作为目录
  • categories 是 开发工具、工作流、Markdown 这类子分类时，自动挂到 技术笔记 下
  • 没写 package 和 categories 时，会按 note_type 或标签推导，最后兜底到 技术笔记

🚀 怎么发布

在当前 vault 目录执行：

1
node .\hexo-publish\publish-note.mjs --config .\hexo-publish\config.deploy.json --hexo-root "<你的 Hexo 仓库路径>" --note ".\Git指南.md"

如果某次只想给单篇文章临时指定封面，可以加 --cover：

1
node .\hexo-publish\publish-note.mjs --config .\hexo-publish\config.deploy.json --hexo-root "<你的 Hexo 仓库路径>" --note ".\Obsidian 发布到 Hexo 工作流.md" --cover "hexo-publish/assets/covers/cover-obsidian-hexo-workflow.png"

先预览所有准备发布的笔记会落到哪里：

1
node .\hexo-publish\publish-note.mjs --config .\hexo-publish\config.deploy.json --hexo-root "<你的 Hexo 仓库路径>" --all --dry-run

批量同步所有 publish: true 的笔记：

1
node .\hexo-publish\publish-note.mjs --config .\hexo-publish\config.deploy.json --hexo-root "<你的 Hexo 仓库路径>" --all

也可以把 Hexo 仓库路径放到环境变量里，命令会更短：

1
2
$env:HEXO_ROOT = "<你的 Hexo 仓库路径>"
node .\hexo-publish\publish-note.mjs --config .\hexo-publish\config.deploy.json --all --dry-run

如果文件里没有 publish: true，脚本会跳过。确实要强制导出时再加 --force。

导出成功后，目标文章会出现在：

1
你的 Hexo 项目/source/_posts/<package>/<slug>.md

如果封面图是本地文件，脚本会复制到 Hexo 静态资源目录：

1
你的 Hexo 项目/source/img/posts/<slug>/

文章 frontmatter 会引用公开路径：

1
/img/posts/<slug>/<image-file>

🔄 脚本会帮你做什么

这个脚本当前会做几件事：

  • 读取 Obsidian frontmatter
  • 把笔记导出为 Hexo frontmatter
  • 自动生成或使用已有 slug
  • 按 package / categories / note_type / tags 推导分包目录
  • 支持 --all 批量发布和 --dry-run 预览
  • 把 [内部链接](//) 转成普通 Markdown 链接
  • 把 ![图片](//) 转成 Hexo 能识别的图片引用
  • 复制封面图到 Hexo 静态资源目录
  • 自动插入 <!-- more --> 摘要分隔符

⚠️ 需要你知道的限制

当前这版是轻量实用版，所以有几条边界：

  • YAML 解析支持常见简单写法，复杂嵌套暂时不建议
  • [笔记](//#标题) 会转成博客内链接，但前提是对应文章也有 slug
  • 复杂 Obsidian embed 语法还没有全部兼容
  • 当前脚本只处理 Markdown 正文和常见 frontmatter，不负责自动改写复杂插件语法
  • 如果封面图写的是本地路径，脚本会复制到对应文章资源目录；如果写的是 https:// 图片，会保持原链接

🎨 封面图怎么用

我已经给你预留了一类图：

  • covers/：适合作为文章封面

推荐用法：

  • 工具类文章用偏实景、桌面、终端、代码感封面
  • 同一系列文章尽量固定 2 到 4 张图循环使用，博客会更整齐

🧭 我建议你的长期用法

最稳的一套是：

  1. 在 Obsidian 里写完整笔记
  2. 给准备公开的文章补 publish / slug / package / note_type / cover
  3. 先执行 --all --dry-run 看分包是否正确
  4. 用 --all 同步到 Hexo
  5. 在 Hexo 本地预览，没问题再部署

这样 Obsidian 是知识库，Hexo 是展示面，它们分工很清楚。

✅ 常用命令

1
2
3
4
5
6
7
8
9
10
11
12
# 预览所有 publish: true 笔记的导出位置
node .\hexo-publish\publish-note.mjs --config .\hexo-publish\config.deploy.json --hexo-root "<你的 Hexo 仓库路径>" --all --dry-run

# 批量发布到 Hexo _posts
node .\hexo-publish\publish-note.mjs --config .\hexo-publish\config.deploy.json --hexo-root "<你的 Hexo 仓库路径>" --all

# 到 Hexo 仓库预览
cd "<你的 Hexo 仓库路径>"
npm run server

# 生成静态站点
npm run build

如果在 Hexo 仓库里执行 npm scripts，可以设置一次 vault 路径：

1
2
3
4
cd "<你的 Hexo 仓库路径>"
$env:OBSIDIAN_VAULT = "<你的 Obsidian vault 路径>"
npm run publish:dry
npm run publish:all

如果不想每次设置环境变量，可以在 Hexo 仓库放一个本机专用配置：

1
2
3
{
  "vaultRoot": "<你的 Obsidian vault 路径>"
}

文件名使用 hexo-publish.local.json，它已经在 Hexo 仓库的 .gitignore 里，不会把本机路径提交出去。