为什么使用Blog Outbox
在开始写博客之前，我个人的写作主要集中在Obsidian中，也已经围绕它搭建了一套比较顺手的写作流程。但是，博客项目与写作仓库并不在同一个目录中。一篇文章写完后，如果要发布到博客，我需要手动复制Markdown文件、搬运图片，再逐个修改图片链接和Obsidian特有的语法。偶尔修改文章时，还要判断两边哪一份才是最新的。次数一多，这些工作就显得既机械又容易出错。
于是，为了减少这部分重复劳动，我在Codex的帮助下，vibe coding了一个Obsidian插件——Blog Outbox。它可以将Obsidian仓库中的Markdown文档发布到本地博客项目，并在这个过程中完成必要的格式适配，例如转换Obsidian的内部链接、复制并重命名图片附件等。整个过程不会改动Obsidian中的源文件；如果目标文件在发布后又被其他工具修改，插件也会在下一次覆盖前给出提示。
从定位上说，Blog Outbox更像一个“本地发件箱”，而不是一套完整的博客发布系统。它负责把文章从Obsidian安全、稳定地交给博客项目，至于网站构建、Git提交以及部署上线，仍然由原本的博客工作流负责。
Blog Outbox的适用范围
Blog Outbox最适合这样的使用场景：平时在Obsidian中写作，博客项目保存在本地，并且能够读取带有YAML Frontmatter的Markdown文件。它不依赖Astro、Hugo或Hexo等某一种特定框架，只要博客能够从指定目录读取文章和静态资源，就可以通过调整路径来适配。
需要注意的是，这是一款桌面端插件。因为它要访问Obsidian仓库之外的本地目录，所以无法在移动端工作。它也不提供远程图床、云同步、Git集成或自动部署。如果你的文章直接写在博客仓库中，或者希望从Obsidian一键发布到线上平台，那么Blog Outbox可能并不是最合适的工具。
Blog Outbox的使用方法
安装
插件上架Obsidian社区插件市场后，可以直接搜索“Blog Outbox”并安装启用。如果暂时无法在市场中找到，也可以前往仓库的Release页面，下载main.js、manifest.json和styles.css，放入仓库的.obsidian/plugins/blog-outbox/目录，然后重载Obsidian并在“第三方插件”中启用。
由于插件会向Obsidian仓库之外写入文件，第一次使用时建议先准备一个测试仓库和一份可随时删除的博客项目副本，确认目录与转换结果符合预期后，再用于正式内容。
配置
启用插件后，打开“设置 → Blog Outbox”。首先填写“博客项目根目录”，这里需要使用本地博客项目的绝对路径。其余设置用于告诉插件文章应该写到哪里、附件应该放到哪里，以及这些文件在网站中对应什么URL。
| 设置 | 默认值 | 用途 |
|---|---|---|
| 博客项目根目录 | 无 | 本地博客项目的绝对路径。 |
| 文章输出目录 | posts | 生成<slug>.md文件的相对目录。 |
| 附件输出目录 | assets | 复制附件的相对目录，应对应博客公开提供资源的目录。 |
| 附件公开URL前缀 | /assets | 写入Markdown附件链接的URL前缀。 |
| 文章公开URL模板 | /posts/{slug}/ | 转换其他已发布笔记链接时使用，必须包含{slug}。 |
| 发布开关字段 | publish | 必须严格等于true的Frontmatter字段。 |
| 发布的YAML字段 | 见下文 | 允许复制到博客Frontmatter中的顶层字段。 |
| 文件冲突策略 | 停止并提示 | 目标位置存在未知文件时停止或跳过该文章。 |
| 允许发布草稿 | 关闭 | 关闭时，draft: true会阻止发布。 |
这里最容易混淆的是“输出目录”和“公开URL”。前者是文件在磁盘上的实际位置，后者是浏览器访问资源时使用的地址，两者不一定相同。例如，博客框架可能要求图片写入public/images，但网页中的链接却是/images/example.png。此时附件输出目录应填写public/images，附件公开URL前缀则填写/images。
“发布的YAML字段”采用白名单方式工作。默认包含title、description、publishDate、updatedDate、category、tags、draft、featured和readingTime。如果博客还需要作者、封面等字段，就需要在这里补上对应的顶层字段名。publish和slug属于插件的控制字段，不会被写入生成文件；其中slug会用来决定文件名和文章链接。
填写完成后点击“验证并保存”。插件会检查路径是否越界、目标目录是否可读写，以及URL模板是否有效。通过验证只代表Blog Outbox能够正确访问这些位置，并不代表配置一定符合博客框架的内容规范，首次发布后仍然需要在博客项目中执行一次原有的构建或预览命令。
使用流程
首先，在准备发布的笔记中加入YAML Frontmatter。对Blog Outbox来说，真正必需的只有发布开关；其他字段是否需要、叫什么名字，取决于博客项目本身。下面是一个比较完整的例子：
---
title: 我的第一篇文章
description: 一段用于文章列表和SEO的简介
publishDate: 2026-09-12
tags:
- Obsidian
- Markdown
draft: false
publish: true
slug: my-first-post
---只有当publish严格等于布尔值true时，文章才会进入待发布范围。slug可以省略，插件会依次尝试根据标题或文件名生成；不过一旦文章准备公开，最好手动设置一个稳定的slug，避免以后修改标题时连带改变文章地址。
准备好后打开命令面板，先运行“Blog Outbox：检查当前文章”或“预览当前文章发布”。检查只会验证内容，预览则会进一步列出将要生成的文章路径、公开URL、需要复制的附件，以及可能出现的警告和冲突，两者都不会写入文件。确认无误后，再运行“发布当前文章”。插件会再次展示发布计划，得到确认后才真正写入博客项目。
如果需要一次处理多篇文章，可以运行“检查所有标记为发布的文章”和“发布所有标记的文章”。批量发布时，每篇文章都作为独立事务处理，因此其中一篇失败不会让已经成功的文章处于写到一半的状态。日常使用中，我更倾向于先发布当前文章，确认博客预览正常后，再使用批量发布更新其他内容。
发布完成后，插件会把源文件哈希、输出文件哈希、目标路径、slug和附件引用记录在自己的本地数据中。再次发布完全相同的内容不会重复写入；如果博客项目中的目标文件在发布后被手动修改，下一次预览也会提示冲突，避免无意间覆盖博客侧的改动。
链接与附件会如何转换
Blog Outbox支持常见的Obsidian图片嵌入，包括![[image.png]]、带替代文本的![[image.png|alt text]]以及标准Markdown图片。对于![[image.png|640]]或![[image.png|640x360]]这类尺寸写法，插件会将尺寸转换为HTML提示，但最终显示效果仍取决于博客的Markdown渲染器与CSS。
本地附件会复制到配置的附件目录，并以内容的SHA-256摘要生成稳定的文件名。这样做有两个好处：同一份附件即使在不同文章中被引用，也只需要保存一份；文件名中也不会再出现空格、中文或同名冲突带来的路径问题。远程的http、https和data:图片则会保持原样，插件不会下载它们。
指向其他Obsidian笔记的内部链接，会在目标笔记同样可以发布时，按照“文章公开URL模板”转换为博客链接。如果目标不存在或没有开启发布，链接会退化为普通文本，同时在预览中给出警告，以免生成一个明知无法访问的死链接。代码块和行内代码中的内容不会参与转换，因此示例代码里的双链也不会被误改。
对于Callout、块引用链接、Canvas链接和整篇笔记嵌入等较为特殊的Obsidian语法，插件会尽量保留内容，但无法保证在所有博客框架中得到一致结果。遇到这类提示时，最稳妥的做法仍然是在博客的本地预览中实际检查一次。
更新、撤回与slug变更
文章内容有修改时，可以直接重新发布。Blog Outbox只会管理由它创建并记录过的文件，不会擅自接管目标目录中原本存在的同名文件；如果目标位置已经有一个不受插件管理的文件，它会根据冲突策略停止或跳过，而不是直接覆盖。
如果想从博客项目中移除文章，可以运行“撤回当前文章”。撤回依据的是插件保存的发布记录，而不是简单地根据文件名猜测。只有当某个附件不再被其他已发布文章引用时，它才会随文章一起移除；如果文章或附件在博客侧被修改过，插件也不会直接删除，而是提示你先检查差异。
修改slug需要稍微谨慎一些。由于slug决定了目标文件名与公开地址，直接改完再发布会被视为另一篇文章，旧文件不会凭空消失。正确的顺序是先用旧slug撤回当前文章，再修改slug并重新发布。这样既不会在博客中留下旧页面，也能让插件的管理记录保持一致。