#+title: webmention.el
#+author: Cytrogen
#+language: zh-CN

从 Emacs 发送 [[https://www.w3.org/TR/webmention/][Webmention]]（W3C 推荐标准）。

Emacs 28.1+ | GPLv3 | v0.1.0

[[docs/README.org][English]]

* 功能

- =webmention-discover= — 抓取文章页面，提取外链，发现 Webmention 端点，打开 staging buffer 供你选择发送
- =webmention-send-url= — 直接发送单条 Webmention（指定 source 和 target）
- =webmention-show-history= — 查看历史发送记录

* 安装

** 手动安装

#+begin_src shell
git clone https://git.cytrogen.icu/~cytrogen/webmention.el ~/.emacs.d/webmention
#+end_src

#+begin_src emacs-lisp
(add-to-list 'load-path "~/.emacs.d/webmention")
(require 'webmention)
#+end_src

** use-package

#+begin_src emacs-lisp
(use-package webmention
  :load-path "~/.emacs.d/webmention"
  :commands (webmention-discover webmention-send-url webmention-show-history)
  :bind (("C-c w d" . webmention-discover)
         ("C-c w s" . webmention-send-url)
         ("C-c w h" . webmention-show-history)))
#+end_src

快捷键仅作参考，请根据自己的配置调整。

* 使用

** 发现并发送（webmention-discover）

这是最常用的入口。典型场景：你发布了一篇博客文章，文中引用了其他站点，想通知它们。

1. =M-x webmention-discover=（或你绑定的快捷键）
2. 输入你的文章 URL（如果光标下有 URL、Org 属性 =WEBMENTION_URL= 或剪贴板中有 URL，会自动作为默认值）
3. 程序抓取页面，提取所有外链，并发现哪些支持 Webmention
4. 弹出 staging buffer，按分类列出所有链接

*** Staging Buffer 操作

| 按键  | 操作             |
|-------+------------------|
| =m=   | 标记当前目标     |
| =u=   | 取消标记         |
| =M=   | 全部标记         |
| =U=   | 全部取消标记     |
| =s= / =RET= | 发送已标记的目标 |
| =g=   | 刷新（重新发现） |
| =n=   | 下一个目标       |
| =p=   | 上一个目标       |
| =q=   | 退出             |

Staging buffer 会将链接分为以下几组：

- *Targets with endpoints* — 支持 Webmention 的目标，可标记发送
- *Sent* — 已成功发送
- *Discovering* — 正在发现端点
- *No endpoint* — 不支持 Webmention
- *Skipped (internal)* — 同域名链接，已自动跳过
- *Errors* — 发现过程中出错

** 直接发送（webmention-send-url）

如果你已经知道要通知哪个页面：

1. =M-x webmention-send-url=
2. 输入 Source URL（你的文章）和 Target URL（对方页面）
3. 自动发现端点并发送

适合脚本化或只需通知单个目标的场景。

** 查看历史（webmention-show-history）

=M-x webmention-show-history= 打开历史记录 buffer，按时间倒序显示所有发送过的 Webmention，包括状态码和时间戳。

历史记录保存在 =~/.emacs.d/webmention-history.eld=。

* 自定义

所有变量均可通过 =M-x customize-group RET webmention= 配置。

| 变量                                  | 默认值                         | 说明                                       |
|---------------------------------------+--------------------------------+--------------------------------------------|
| =webmention-user-agent=              | ="Emacs-Webmention/0.1"=      | HTTP 请求的 User-Agent 字符串              |
| =webmention-timeout=                 | =30=                           | HTTP 请求超时（秒）                        |
| =webmention-max-concurrent-requests= | =4=                            | 端点发现的最大并发数                       |
| =webmention-history-file=            | =~/.emacs.d/webmention-history.eld= | 历史记录文件路径                     |
| =webmention-skip-internal-links=     | =t=                            | 是否跳过同域名链接                         |
| =webmention-confirm-resend=          | =t=                            | 重复发送时是否确认                         |
| =webmention-max-response-size=       | =1048576= (1 MB)              | 最大响应体大小（字节），超出则截断         |
| =webmention-history-max-entries=     | =500=                          | 历史记录最大条数，超出则清理最旧的         |
| =webmention-max-retries=             | =2=                            | 瞬态错误（5xx、超时）的重试次数，0 禁用   |
| =webmention-debug=                   | =nil=                          | 启用后将日志写入 =*Webmention Log*= buffer |

* 什么是 Webmention？

[[https://www.w3.org/TR/webmention/][Webmention]] 是 W3C 推荐的 Web 标准协议。当你的文章链接了另一个站点时，可以通过 Webmention 通知对方"我提到了你"。

它是 Pingback 的现代替代方案，广泛用于 [[https://indieweb.org/][IndieWeb]] 社区。支持 Webmention 的站点会在页面中声明一个端点（通过 HTTP Link header 或 HTML =<link>= 标签），接收方可以据此展示评论、点赞、转发等互动信息。

适用场景：
- 独立博客之间的互相通知
- 跨站评论和互动
- 去中心化的社交网络交互

* 许可证

GPLv3。详见 [[https://www.gnu.org/licenses/gpl-3.0.html][GNU General Public License v3.0]]。