#+TITLE: hexo-mastodon-syndicate
#+AUTHOR: Cytrogen
#+DESCRIPTION: 将 Hexo 博客文章联合发布到 Mastodon

* hexo-mastodon-syndicate

一个 Hexo 项目用的 Mastodon 联合发布脚本，实现 [[https://indieweb.org/POSSE][POSSE]]（Publish on your Own Site, Syndicate Elsewhere）工作流。

** 工作流程

1. 在文章的 front matter 中添加 =syndicate: true=
2. 运行脚本，自动发送 Mastodon 帖子（包含标题、摘要和链接）
3. 脚本将 =syndicate: true= 替换为 =syndication: <Mastodon 帖子 URL>=
4. 提交修改后的文件并部署

** 安装

*** 方式一：npm 安装

#+begin_src shell
npm install --save-dev hexo-mastodon-syndicate
#+end_src

*** 方式二：直接复制

将 =syndicate.js= 复制到你的 Hexo 项目中即可使用。

** 配置

*** 方式一：_config.yml

在 Hexo 的 =_config.yml= 中添加以下配置段：

#+begin_src yaml
diary_sources:
  mastodon:
    server: https://your.mastodon.instance
    access_token: your_access_token_here
#+end_src

脚本会自动读取 =_config.yml= 中的 =url= 字段作为博客地址。

*** 方式二：环境变量

设置以下环境变量即可，无需修改 =_config.yml=：

| 环境变量                 | 说明                     | 必填 |
|--------------------------+--------------------------+------|
| =MASTODON_SERVER=        | Mastodon 实例地址        | 是   |
| =MASTODON_ACCESS_TOKEN=  | Mastodon 访问令牌        | 是   |
| =SYNDICATE_SITE_URL=     | 博客站点 URL             | 是   |

环境变量也可以和 =_config.yml= 混合使用，环境变量的优先级更高。

*** Mastodon 访问令牌

前往你的 Mastodon 实例的 =设置 → 开发 → 新建应用=，创建一个具有 =write:statuses= 权限的访问令牌。

** 可选：Org 文件同步

如果你使用 Org-mode 写作，脚本可以同时更新对应的 =.org= 源文件，在其中添加 =#+SYNDICATION:= 属性。

设置 =SYNDICATE_ORG_DIR= 环境变量指向你的 Org 文件目录：

#+begin_src shell
export SYNDICATE_ORG_DIR=~/Documents/Org/blog/posts
#+end_src

未设置此变量时，Org 文件同步功能自动跳过。

** 可选：自定义文章目录

默认扫描 =source/_posts= 目录。如需更改：

#+begin_src shell
export SYNDICATE_POSTS_DIR=source/_articles
#+end_src

** 用法

在 Hexo 项目根目录运行：

#+begin_src shell
# 通过 npx
npx hexo-mastodon-syndicate

# 或直接运行
node node_modules/hexo-mastodon-syndicate/syndicate.js

# 如果是直接复制的脚本
node syndicate.js
#+end_src

脚本只负责联合发布和更新文件，不会自动提交或推送。

** 一键发布（syndicate + commit + push）

如果你的项目通过 =git push= 自动触发部署（如 VPS 上的 Git hook、GitHub Pages、Netlify 等），可以使用 =hexo-mastodon-publish= 一键完成整个流程：

#+begin_src shell
npx hexo-mastodon-publish
#+end_src

它的完整流程：

1. 检查工作区是否干净（有未提交的改动会报错退出）
2. 运行联合发布
3. 自动 =git commit= 修改后的文件
4. =git push= 到当前分支的上游远程

** 文章示例

#+begin_src yaml
---
title: 我的新文章
date: 2026-01-01 12:00:00
syndicate: true
abbrlink: abc123
---
#+end_src

运行脚本后，=syndicate: true= 会被替换为：

#+begin_src yaml
syndication: https://your.instance/@you/123456789
#+end_src

** 许可证

[[file:LICENSE][MIT]]