What the agent does
The agent first learns how the blog's posts and tags are wired, because a related-posts list has to use the same collections the templates already use. In a site built from 11ty/eleventy-base-blog, content/blog/blog.11tydata.js gives every file in content/blog/ the posts tag and the layouts/post.njk layout, so collections.posts is the list to rank. The five posts carry small tag sets: firstpost.md has another tag, secondpost.md has number 2, thirdpost.md has second tag and posts with two tags, fourthpost/fourthpost.md has second tag, and fifthpost.md is draft: true, which the drafts preprocessor in eleventy.config.js drops from a production build. _config/filters.js already has filterTagList, which strips all and posts, and _includes/layouts/post.njk already renders the tag list and a previous-and-next block built from getPreviousCollectionItem and getNextCollectionItem.
It adds one filter, relatedPosts, to _config/filters.js, next to head, min and filterTagList, so it is registered through the same eleventyConfig.addPlugin(pluginFilters) call and needs no change to eleventy.config.js. The filter takes the current page, collections.posts and a limit, defaulting to 3. It drops the page itself, counts tags in common after passing both tag lists through the same all and posts exclusion filterTagList uses, keeps only posts with at least one shared tag, and sorts by shared count and then by how close the two dates are, so a tie between two posts on second tag goes to the nearer one in time. Drafts need no special handling: in a build they are already gone from the collection, and in --serve they appear with the (draft) title suffix the preprocessor adds, which is what the author expects while previewing.
The markup goes into post.njk between the post body and the links-nextprev block: a heading and the existing postslist.njk include, with postslist set to the filter's result, so related posts get the same .postlist styling, dates and postlist-link class as the archive on blog.njk, and the whole block is wrapped in a condition so a post with nothing related, like firstpost.md, shows no empty heading. A few lines in css/index.css tighten the spacing under the body; the agent keeps them beside the .links-nextprev rules rather than adding a new stylesheet, because base.njk inlines css/index.css into the per-page CSS bundle.
The proof is the output. The agent runs npm ci on Node 22 from .nvmrc and npm run build, which runs @11ty/eleventy 3.1.7 into _site/, then reads _site/blog/thirdpost/index.html and shows the related list naming the fourth post through second tag, reads _site/blog/fourthpost/index.html and shows the third post, and reads _site/blog/firstpost/index.html to show no related section at all. It also runs npm run start long enough to confirm the draft fifth post renders with the block in serve mode without an error, since page.date on a draft is still a real date.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a related-posts section to every blog post in this Eleventy site. Read eleventy.config.js, _config/filters.js, content/blog/blog.11tydata.js, _includes/layouts/post.njk, _includes/postslist.njk and css/index.css first. Add a relatedPosts filter in _config/filters.js that ranks collections.posts by tags shared with the current post, ignoring the all and posts tags, breaks ties by date proximity, excludes the post itself and returns at most three. Render them in post.njk above the previous and next links using the existing postslist include, and show nothing when there is no related post. Run the build on the Node version in .nvmrc and quote the related list from the built HTML of two posts and the absence of it on a post with no shared tags. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 on its own branch touching three files: _config/filters.js with the new filter, _includes/layouts/post.njk with the conditional block, and css/index.css with a few spacing rules. eleventy.config.js, the posts themselves and _data/metadata.js are unchanged, so the pull request reads as one feature rather than a reformat.
The description quotes the related section from the built HTML of thirdpost and fourthpost, shows that firstpost has none, and includes the npm run build summary line with the number of files written. It explains the ranking in two sentences, shared tags first and date distance second, and notes that the limit is a filter argument the template passes, so changing three to five is a one-character edit in post.njk.
Before merging, a reviewer reads the filter once to confirm all and posts are excluded, since without that every post would be related to every other, and checks the rendered block against the site's look in a local npm run start. The pull request links back to the Linear issue that asked for it.
Run it on every Linear issue labelled agent
In the console, an automation with a linear trigger on linear.issue.labeled and the label agent starts one run per labelled issue in the Project that holds the blog's repository, with the issue text as its context. The trigger adds the issue after the prompt; an issue that says "show three related posts under each post, by tag" is enough for the agent to find collections.posts and post.njk on its own. Changes made by an app integration never fire it, so the agent's own comments on the issue start nothing.
From your own server, the same run is one POST /o/{org}/sessions per issue with this body: the repository in resources, and the issue's https://linear.app/<workspace>/issue/<ID> URL there too so Rush reads it through your Linear connection into the prompt. Send a request_id, a UUID v5 of the issue id, so a redelivered event does not start a second run.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
The feature is small but the mistakes are specific to Eleventy: forgetting that every post carries the posts tag, so a naive overlap count relates everything to everything; ranking inside the template with nested loops, which Nunjucks makes slow and unreadable; or breaking the draft preview. The agent reads filterTagList and the drafts preprocessor before writing anything, and reuses postslist.njk so the result matches the archive page without new CSS classes.
On Rush the build runs in the agent's own sandbox on the Node version the repository names, and the transcript keeps the build output and the HTML it read, so the pull request's claims about which post relates to which are checkable without a local checkout. A blog with hundreds of posts gets the same treatment, since the ranking is a filter over the collection rather than hand-written links.
Frequently asked questions
Will it edit my posts or their front matter?
No. The ranking uses the tags each post already declares and the posts tag blog.11tydata.js adds to the directory. No Markdown file changes. If your posts have few tags, the description says so and suggests adding a tag or two where related posts should appear.
What happens on a post with no shared tags?
Nothing is rendered. The block in post.njk is wrapped in a condition on the filter's result, so a post like firstpost.md, whose only tag is another tag, shows the previous-and-next links as before with no empty heading above them. The agent quotes that page's HTML in the description to show it.
Does it slow the build?
Not measurably at blog size. The filter runs once per post and compares small tag arrays, and Eleventy's own getPreviousCollectionItem already walks the same collection for every post. The agent reads the build's summary line before and after and reports both numbers in the description.
Can related posts be chosen by hand for some posts?
Yes, with a small extension: a related front matter key listing file slugs, which the filter honours before falling back to tags. The agent does not add it unless the issue asks, because the base blog has no such key, but the filter is written so the override is a few lines.
More Eleventy jobs
The same job on other stacks
- Add Related Posts to a Gatsby Blog (Gatsby)
- Add Related Posts to a Hugo Blog (Hugo)
- Add Related Posts to a Jekyll Blog (Jekyll)