Markdown 文章推送

一个基于 Obsidian 的 Markdown 文章推送插件。

功能

• 手动推送当前打开的 Markdown 文件到配置的 Web API。
• 支持通过左侧 ribbon 图标或命令面板执行“推送当前 Markdown 文章”。
• 使用 JSON 作为请求体，包含文章标题、路径、正文、Frontmatter、标签和发布状态。
• 推送前扫描本地图片链接，发现后提示“请确保图片已上传至图床”，用户确认后才继续推送。
• 推送成功后在 Obsidian 中提示，并把文档属性标记为 已发布。
• 已发布文章被再次修改后，自动把文档属性改为 待同步，方便识别需要重新同步的内容。

配置

在插件设置里填写目标博客的 API 接口地址。

• 设置项名称：目标博客 API 接口
• 示例：https://example.com/api/posts
• 请求方式固定为：POST
• 请求头固定包含：Content-Type: application/json; charset=utf-8 和 Accept: application/json

安装

1. 将 markdown-push 目录放到目标 Obsidian 仓库的 .obsidian/plugins/ 目录下。
2. 在 Obsidian 中打开“设置 -> 第三方插件”，关闭安全模式后启用“Markdown 文章推送”。
3. 打开插件设置，填写目标博客 API 接口。
4. 打开要推送的 Markdown 文件，使用左侧 ribbon 图标或命令面板里的“推送当前 Markdown 文章”。

使用方法

1. 打开需要发布或同步的 Markdown 文件。
2. 确认文章中的图片已经是线上图片地址；如果仍包含本地图片链接，插件会在推送前弹窗提醒。
3. 点击 Obsidian 左侧栏的上传图标，或打开命令面板执行“推送当前 Markdown 文章”。
4. 推送成功后，插件会显示成功提示，并更新当前文档的发布属性。
5. 如果后续修改已发布文章，插件会自动把文章标记为 待同步。

文档属性

推送成功后，插件会写入或更新这些 Frontmatter 字段：

• publish_status: 已发布
• published: true
• published_at：首次发布成功时间，ISO 8601 字符串。
• last_pushed_at：最近一次成功推送时间，ISO 8601 字符串。
• last_synced_at：最近一次成功同步时间，ISO 8601 字符串。

已发布文章再次修改时，插件会自动写入或更新：

• publish_status: 待同步
• published: true
• needs_sync: true
• last_modified_at：最近一次修改时间，ISO 8601 字符串。

后端接口配置

后端需要提供一个可接收 JSON 请求体的 HTTP 接口。插件会向配置的 API 地址发送 POST 请求。

请求体

插件会发送一个 JSON 对象，包含：

• title：文章标题。优先取 Frontmatter 中的 title，否则使用文件名。
• filePath：文章在 Obsidian 仓库中的路径。
• fileName：Markdown 文件名。
• content：完整 Markdown 正文。
• frontmatter：Obsidian 解析到的 Frontmatter 对象。
• tags：文章标签数组，不包含开头的 #。
• source：固定为 obsidian。
• status：当前 publish_status 值，没有则为空字符串。
• published：当前 published 值转换后的布尔值。

示例：

{
  "title": "示例文章",
  "filePath": "posts/example.md",
  "fileName": "example.md",
  "content": "---\ntitle: 示例文章\n---\n\n正文内容",
  "frontmatter": {
    "title": "示例文章",
    "publish_status": "待同步"
  },
  "tags": ["blog", "obsidian"],
  "source": "obsidian",
  "status": "待同步",
  "published": true
}

响应要求

后端返回任意 2xx HTTP 状态码都会被插件视为推送成功，例如 200、201、204。

响应体没有强制格式要求。建议返回 JSON，方便后续扩展：

{
  "success": true,
  "id": "post-123",
  "url": "https://example.com/posts/example"
}

如果返回非 2xx 状态码，插件会视为推送失败，并在 Obsidian 中展示状态码和响应内容的前 300 个字符。建议后端在失败时返回清晰的错误信息：

{
  "success": false,
  "message": "title is required"
}

后端需要处理的事项

• 允许接收 POST 请求。
• 正确解析 application/json; charset=utf-8 请求体。
• 根据 filePath、fileName、title 或后端自己的规则判断是新建文章还是更新文章。
• 保存 content 中的完整 Markdown 内容。
• 按需保存 frontmatter、tags、source、status 和 published。
• 如果接口有鉴权、签名、Token 或 Cookie 要求，需要先在后端或网关侧放行当前插件请求；当前插件版本只支持配置 API 地址，不支持在插件设置中配置额外请求头。
• 如果前端页面不能直接访问该接口，需要在后端配置 CORS，允许来自 Obsidian 环境的请求。

注意事项

• 插件不会上传本地图片，只会提示用户确认图片是否已经上传到图床。
• 插件不会解析后端返回的文章 ID 或 URL，也不会把它们写回文档属性。
• 当前版本只支持一个目标 API 地址。