# Add Related Posts by Shared Tags to an Eleventy Blog

Yes. An agent adds a related-posts filter that ranks your Eleventy posts by shared tags, renders up to three under each post, and proves it in the built HTML.

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

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

```json
{
  "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"
    }
  ]
}
```

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 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.

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

- [Add Search to an Eleventy Blog from a Linear Issue](https://getrush.ai/run/add-search/eleventy/)
- [Add Security Headers and a CSP to an Eleventy Site](https://getrush.ai/run/add-security-headers/eleventy/)
- [Add Social Cards to an Eleventy Blog](https://getrush.ai/run/add-social-cards/eleventy/)

## The same job on other stacks

- [Add Related Posts to a Gatsby Blog](https://getrush.ai/run/add-related-posts/gatsby/)
- [Add Related Posts to a Hugo Blog](https://getrush.ai/run/add-related-posts/hugo/)
- [Add Related Posts to a Jekyll Blog](https://getrush.ai/run/add-related-posts/jekyll/)

## 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/)
