如果你习惯在本地用 Markdown 写文章，Obsidian 可能是你最常用的工具之一。它的本地化管理、双向链接和插件生态，让不少写作者把整个内容创作流程都搬了进去。
Halo 社区维护了一个 Obsidian 插件，可以直接把 Obsidian 中的文章发布到 Halo 站点，包括文章里的本地图片也会自动上传。这篇文章介绍怎么配置和使用它。
插件的 GitHub 仓库：halo-sigs/obsidian-halo，当前最新版本 v1.2.0。
一、装个 Obsidian（如果你还没有）
Obsidian 是一个基于本地 Markdown 文件的知识管理和笔记工具。和 Notion 这类在线工具不同，Obsidian 的所有数据都存储在本地的 .md 文件中，这意味着：
- 完全离线可用，不需要网络。
- 数据归你自己，不依赖任何云服务。
- 几百个社区插件可以扩展各种功能，包括发布到各类 CMS。
官网下载 即可，Windows、macOS、Linux、iOS、Android 都支持。
二、安装 Halo 插件
打开 Obsidian，进入 设置 → 社区插件，点击「浏览」，搜索 Halo：
找到插件后点击「安装」，再点击「启用」即可。如果社区插件市场打不开，可以到 GitHub Releases 下载 main.js 和 manifest.json，手动放到 vault 的 .obsidian/plugins/halo/ 目录下。
三、配置 Halo 站点
插件启用之后，在 设置 → 社区插件 → Halo 中找到「Halo 发布设置」界面，点击「添加」来添加你的 Halo 站点。
填写以下信息：
- 站点名称：随便起，方便你在多个站点之间区分。
- 站点地址：你的 Halo 站点 URL，比如
https://www.halo.run。 - 个人令牌：Halo 的个人访问令牌，需要包含文章管理权限。
填好之后可以点「验证」测试连接是否正常。验证通过后点「保存」。
怎么获取个人令牌
登录你的 Halo 后台，进入 用户中心 → 个人令牌，创建一个新的令牌：
注意两点：
- 权限选择：勾选
文章管理员即可。 - 保存令牌：创建成功后令牌只显示一次，务必复制保存。丢了只能重新创建一个。
额外两个设置项
配置站点之外，插件还有两个实用开关：
- 默认发布文章：开启后，首次发布文章时会直接发布（而不是保存为草稿）。如果你对自己的内容比较有把握、不想每次再去后台点一次发布，可以打开这个选项。
- 替换图片链接：默认开启。上传图片后自动把本地路径替换为 Halo 的远程 URL。如果你希望保留本地路径（比如配合其他图床工具），可以关掉它。
多站点和默认站点
如果你有多个 Halo 站点（比如一个正式站、一个测试站），可以添加多个配置。在站点列表中，勾选某个站点的「是否设置为默认」，之后用默认配置发布时就会发到这个站点。
另外，Obsidian 左侧边栏的插件功能区会多出一个 Halo 图标，点击它就是「发布当前文档到 Halo」的快捷入口。
四、发布文章到 Halo
配置好之后，发布过程非常简单。在 Obsidian 中打开一篇写好的文章，按 Cmd+P（macOS）或 Ctrl+P（Windows/Linux）打开命令面板，输入 Halo，你会看到两个发布命令：
- 发布到 Halo：选择站点后发布（多个站点时用）。
- 发布到 Halo（使用默认配置）：直接发布到默认站点。
选一个命令，插件会自动做两件事：
- 上传图片：扫描文章中引用的本地图片，上传到 Halo 的附件库，并将 Markdown 中的本地路径替换为 Halo 的远程 URL。支持的图片格式包括标准的
和 Obsidian 特有的 wiki 风格![[image]]嵌入。 - 发布文章：将文章标题、内容和元数据同步到 Halo。
发布后的文章会出现在 Halo 后台的「文章」列表中，状态为草稿。你可以在 Halo 后台继续编辑、设置分类标签、调整 SEO 信息，最后点击发布。
五、只上传图片，不发布文章
有时候你只是想先把文章里的本地图片上传到 Halo，换成远程链接，但并不想现在就发布。比如你还在写草稿阶段，不想在后台生成一堆半成品。
这时候可以用 上传图片到 Halo 命令。它只做图片上传和链接替换这一步，不会创建或更新文章。
这个命令在协作场景下也很有用——你把本地 Markdown 发给别人时，对方看到的是远程图片链接而不是本地路径。
六、从 Halo 拉取文章到本地
如果你之前已经在 Halo 后台写了一些文章，想把它们同步到 Obsidian 中编辑，可以用 从 Halo 拉取文档 命令。
插件会列出你 Halo 站点上的文章，选择对应的文章后，它会以 Markdown 格式下载到你的 Obsidian vault 中。拉取下来的文章可以直接在 Obsidian 里编辑。
当你修改了拉取下来的文章后，再用「发布到 Halo」命令发布，Halo 那边对应的文章就会被更新（而不是创建一篇新的）。
七、从 Halo 更新本地内容
如果你的文章在 Halo 后台被人修改过了（比如团队协作中其他人更新了内容），或者你自己在后台做了修改但忘了同步到 Obsidian，可以用 从 Halo 更新内容 命令。
它会用 Halo 上对应文章的最新内容覆盖当前 Obsidian 中的笔记。这个操作不可逆，建议在操作前确认你真的想覆盖本地内容。
八、几个实用建议
1. 文章属性映射
插件发布时，Obsidian 笔记的文件名会作为 Halo 文章的标题（如果 YAML frontmatter 中没有 title 字段的话）。建议在笔记开头写上 YAML frontmatter：
---
title: 文章标题
slug: article-slug
---
这样发布到 Halo 时会使用你指定的标题和别名，不用再去后台改。
2. 图片存放位置
Obsidian 的图片附件默认存放在 vault 的根目录或指定的附件文件夹。如果图片路径比较乱，建议在 Obsidian 设置中把「附件文件夹路径」统一设为一个目录（比如 assets），方便管理和迁移。
3. 配合图床使用
如果你希望图片上传到专门的图床而不是 Halo 附件库，可以配合 Image auto upload 插件，先把本地图片上传到图床、替换链接，再用 Halo 插件发布。这样图片和图床绑定，和 Halo 的附件库解耦，将来迁移站点时更灵活。
4. 快速发布快捷键
如果你经常用默认站点发布，可以在 Obsidian 设置中给「发布到 Halo（使用默认配置）」绑定一个快捷键，写完文章一键发布，不用每次都打开命令面板。
以上就是在 Obsidian 中发布文章到 Halo 的完整流程。这个插件由 Halo 社区维护，如果你在使用过程中遇到问题，可以去 GitHub Issues 反馈。
关于 Halo 的更多使用技巧，可以看看 在 Halo 中使用 Markdown 写作的 6 种方式 和 让 AI Agents 管理 Halo 网站内容。