#+title: webmention.el
#+author: Cytrogen
#+language: en

Send [[https://www.w3.org/TR/webmention/][Webmentions]] (W3C Recommendation) from Emacs.

Emacs 28.1+ | GPLv3 | v0.1.0

[[https://git.cytrogen.icu/~cytrogen/webmention.el/tree/main/item/README.org][中文]]

* Features

- =webmention-discover= — Fetch a page, extract outbound links, discover Webmention endpoints, and open a staging buffer for selective sending
- =webmention-send-url= — Send a single Webmention directly (given source and target URLs)
- =webmention-show-history= — View previously sent Webmentions

* Installation

** Manual

#+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

Keybindings are suggestions only — adjust to your preference.

* Usage

** Discover & Send (webmention-discover)

The primary entry point. Typical scenario: you published a blog post that links to other sites and want to notify them.

1. =M-x webmention-discover= (or your bound key)
2. Enter your article URL (defaults to URL at point, the Org =WEBMENTION_URL= property, or a URL in the kill ring)
3. The package fetches the page, extracts all outbound links, and discovers which support Webmention
4. A staging buffer opens with links grouped by category

*** Staging Buffer Keys

| Key   | Action                |
|-------+-----------------------|
| =m=   | Mark target           |
| =u=   | Unmark target         |
| =M=   | Mark all              |
| =U=   | Unmark all            |
| =s= / =RET= | Send marked targets |
| =g=   | Refresh (re-discover) |
| =n=   | Next target           |
| =p=   | Previous target       |
| =q=   | Quit                  |

The staging buffer groups links into sections:

- *Targets with endpoints* — Webmention-capable targets, ready to mark and send
- *Sent* — Successfully sent
- *Discovering* — Endpoint discovery in progress
- *No endpoint* — Target does not support Webmention
- *Skipped (internal)* — Same-domain links, automatically skipped
- *Errors* — Discovery failed

** Direct Send (webmention-send-url)

When you already know the exact target:

1. =M-x webmention-send-url=
2. Enter the Source URL (your article) and Target URL (their page)
3. The endpoint is discovered and the Webmention is sent automatically

Useful for scripting or notifying a single target.

** View History (webmention-show-history)

=M-x webmention-show-history= opens a buffer listing all previously sent Webmentions in reverse chronological order, including HTTP status codes and timestamps.

History is stored in =~/.emacs.d/webmention-history.eld=.

* Customization

All variables can be configured via =M-x customize-group RET webmention=.

| Variable                              | Default                        | Description                                    |
|---------------------------------------+--------------------------------+------------------------------------------------|
| =webmention-user-agent=              | ="Emacs-Webmention/0.1"=      | User-Agent string for HTTP requests            |
| =webmention-timeout=                 | =30=                           | HTTP request timeout in seconds                |
| =webmention-max-concurrent-requests= | =4=                            | Max concurrent endpoint discovery requests     |
| =webmention-history-file=            | =~/.emacs.d/webmention-history.eld= | Path to the history file                 |
| =webmention-skip-internal-links=     | =t=                            | Skip same-domain links during discovery        |
| =webmention-confirm-resend=          | =t=                            | Prompt before resending a previous Webmention  |
| =webmention-max-response-size=       | =1048576= (1 MB)              | Max response body size in bytes (truncated)    |
| =webmention-history-max-entries=     | =500=                          | Max history entries; oldest pruned on save     |
| =webmention-max-retries=             | =2=                            | Retries for transient errors (5xx, timeout)    |
| =webmention-debug=                   | =nil=                          | Log to =*Webmention Log*= buffer when non-nil |

* What is Webmention?

[[https://www.w3.org/TR/webmention/][Webmention]] is a W3C Recommendation for notifying a URL when you link to it. It is the modern replacement for Pingback, widely adopted in the [[https://indieweb.org/][IndieWeb]] community.

Sites that support Webmention declare an endpoint via an HTTP =Link= header or an HTML =<link>= tag. Receivers can then display mentions as comments, likes, reposts, and other interactions.

Use cases:
- Cross-site notifications between independent blogs
- Decentralized comments and interactions
- Federated social web interactions

* License

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