# Add Webmentions to an Eleventy Blog

Yes. An agent adds a webmention.io feed fetched at build time, h-entry markup on posts, a replies and likes block in the post layout, a token-free build, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-webmentions/eleventy/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the site's build before adding a data source. In a site like 11ty/eleventy-base-blog, `package.json` at version 9.0.0 is an ES module on `@11ty/eleventy` 3.1.7 with the image, navigation, RSS and syntax highlight plugins, Luxon and Zod, and `.nvmrc` pins Node 22. `eleventy.config.js` sets `content` as the input directory with `_includes` and `_data` beside it and `_site` as output, drops drafts in a build, bundles CSS and JS per page, serves an Atom feed at `/feed/feed.xml` with `https://example.com/` as its base, and transforms images. `_data/metadata.js` holds the title, `url`, language and author. `_includes/layouts/post.njk` prints the title, a `post-metadata` list with the date and tags, the content, and previous and next links from `getPreviousCollectionItem`; `base.njk` adds the feed `link` in the head and inlines the CSS bundle. Posts under `content/blog/` get the `posts` tag from `blog.11tydata.js`. The sample GitHub Pages workflow already caches `./.cache` under an `eleventy-fetch-cache` key, a directory nothing in the repository writes to yet. No page carries `h-entry` markup, so a reply to a post from another site has nothing to parse, and nothing on the site shows the replies that arrive.

The agent adds `@11ty/eleventy-fetch` as a dev dependency and writes `_data/webmentions.js`, which reads the domain from `metadata.url`, takes the API token from the `WEBMENTION_IO_TOKEN` environment variable, and fetches `https://webmention.io/api/mentions.jf2` for that domain with a one-day cache in `.cache`, so a build repeats the request at most once a day and the Pages workflow's cache carries it between runs. With no token set the file logs one line and returns an empty `children` list, which keeps `npm run build` working on a fork or a first checkout. In `_config/filters.js` it adds `webmentionsForUrl`, which matches each mention's `wm-target` against the page's full URL with and without a trailing slash and sorts by `published`, and `webmentionsByType`, which groups by `wm-property` into likes, reposts, replies and mentions.

In `_includes/layouts/post.njk` it adds `h-entry` to the article wrapper, `p-name` on the title, `dt-published` on the existing `time`, `e-content` around the content and a `p-author h-card` with the author's name and URL from `metadata.js`, so other sites' parsers find the post's author and date. Below the previous and next links it includes a new `_includes/webmentions.njk`: a count line for likes and reposts with the authors' photos, then each reply with the author's name linked to their site, the published date through the existing `readableDate` filter, and the `content.text` of the reply, escaped. `base.njk` gets `rel="webmention"` and `rel="pingback"` links in the head pointing at webmention.io for the domain. Styles for the block go in `css/index.css` next to the `links-nextprev` rules, and `.cache/` is confirmed ignored by Git.

The build is the test. The agent runs `npm run build` once with the variable unset and once with a token, and both produce `_site` with the post layout rendering the block or an empty section. A `node --test` file for the two filters feeds them a fixture of `jf2` entries and checks the URL matching, the trailing-slash case and the grouping; `package.json` gains a `test` script that runs it. The pull request describes the webmention.io setup the reader does once: sign in with the site's domain, copy the token, and set it as a secret in the deploy environment.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add webmentions to this Eleventy blog using webmention.io. Read package.json, eleventy.config.js, _data/metadata.js, _config/filters.js, _includes/layouts/base.njk, _includes/layouts/post.njk, content/blog/blog.11tydata.js, css/index.css, .gitignore and .github/workflows/gh-pages.yml.sample first. Add @11ty/eleventy-fetch and a _data/webmentions.js that fetches the mentions.jf2 feed for the domain in metadata.url with the token from the WEBMENTION_IO_TOKEN environment variable, caches for one day in .cache, and returns an empty list when the token is unset. Add filters that select mentions for a page URL with and without a trailing slash and group them by wm-property. Add h-entry, p-name, dt-published, e-content and a p-author h-card to the post layout, include a webmentions block after the previous and next links showing likes and reposts with author photos and replies with author, date and text, add webmention and pingback link elements to the head, and style the block in css/index.css. Make sure .cache is ignored. Run npm run build with and without the variable, write a node --test file for the filters with a test script, and open a pull request that explains the one-time webmention.io setup.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `_data/webmentions.js`, `_includes/webmentions.njk` and a filter test, edits `_config/filters.js`, `_includes/layouts/post.njk`, `_includes/layouts/base.njk`, `css/index.css` and `package.json`, and adds the dependency to the lockfile. The description names the environment variable, the one-day cache, the microformats added to each post and the one-time webmention.io setup.

The run's record keeps both `npm run build` logs, the one without a token showing the skip line and the one with a token showing the fetch and cache write, plus the `node --test` output with each filter case named, so a reviewer can see the build does not depend on the secret and the URL matching handles the trailing slash the site's `vercel.json` adds.

Before merging, a reviewer opens a built post in `_site`, confirms the `h-entry` markup with a microformats parser, sets the token in the deploy environment and triggers a build, and checks that a known reply to an existing post renders under it with the author's name and date.

## Run it on every Linear issue labelled community

In the console, an automation with a `linear` trigger on `linear.issue.labeled` and the label `community` starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so an issue asking for likes to be hidden or for a reply form carries that request itself and the prompt stays fixed. Changes made by an app integration never fire it, and the automation's `max_runs_per_hour` bounds a burst of labelling.

From your own server, the same job is one `POST /o/{org}/sessions` per issue, with the repository in `resources` and the issue's `https://linear.app/<workspace>/issue/<ID>` URL beside it so Rush reads the issue through your Linear connection. A `webhook_url` on the API key receives `run.completed` or `run.failed` for every run that key starts, with the `session_url` to read the pull request link from.

## Why run it on Rush?

Webmentions touch three layers at once, a build-time fetch, a data filter and a layout, and each fails quietly: a fetch that throws when the token is missing breaks every fork's build, a target match that ignores the trailing slash shows no replies on a site that adds one, an `h-entry` without `dt-published` gets parsed with no date. The agent runs the real build twice in its own sandbox and tests the filters against fixture data, which is the only way to see those failures before deploy.

The commands and their output stay with the run, so the pull request can point at the build log that ran without the secret and at the filter test that covers the slash, and a reviewer checks the claim against the record rather than against the description.

## Frequently asked questions

### Does the build need the webmention.io token?

No. Without `WEBMENTION_IO_TOKEN` the data file returns an empty list and logs that it skipped the fetch, so forks, pull request previews and a first checkout build cleanly. The token is set once in the deploy environment, and the one-day cache in `.cache` keeps builds from hitting the API every time.

### Will my old posts receive webmentions?

Receiving needs the `rel="webmention"` link in the head and the `h-entry` markup on the post, both of which the layout now provides for every post, old and new. Replies sent before the endpoint existed were never delivered and cannot be recovered.

### Does this send webmentions when I link to other sites?

No. Sending is a separate step, a request to each linked site's endpoint after a post is published, and it is not in this change. The pull request notes it as a follow-up, with the Atom feed at `/feed/feed.xml` as the input a sender would read.

### What about the trailing slash?

The site's `vercel.json` sets `trailingSlash` to true and Eleventy writes directory URLs, so a mention's target may arrive with or without the slash. The `webmentionsForUrl` filter compares both forms, and the test covers that case.

## More Eleventy jobs

- [Dockerize an Eleventy Site](https://getrush.ai/run/dockerize-app/eleventy/)
- [Upgrade an Eleventy Site's npm Dependencies Every Week](https://getrush.ai/run/upgrade-npm-dependencies/eleventy/)
- [Write Playwright Tests for an Eleventy Blog](https://getrush.ai/run/write-playwright-tests/eleventy/)

## More jobs like this: Turn a Linear label into a PR

- [Add WebSockets to a Leptos App](https://getrush.ai/run/add-websockets/leptos/)
- [Add a WebSocket Endpoint to a Vapor App from a Linear Issue](https://getrush.ai/run/add-websockets/vapor/)
- [Add a New Page Type to a Wagtail Site from a Linear Issue](https://getrush.ai/run/add-workshop-page/wagtail/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
