# Add Related Posts to a Jekyll Blog

Yes. An agent adds a related posts list to a Jekyll Now blog that matches on tags in plain Liquid, since GitHub Pages cannot run LSI, builds it and opens a PR.

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

## What the agent does

The agent starts with what Jekyll offers and why it is not enough here. `site.related_posts` exists on every page, but Jekyll's documentation says that by default it holds the ten most recent posts, and only a build with the `--lsi` flag turns it into posts that are actually similar. GitHub Pages builds without that flag and the `github-pages` gem does not carry the classifier it needs, and in a blog started from barryclark/jekyll-now there is no Gemfile to add one to, because `.gitignore` excludes it and the README's workflow is `gem install github-pages`. So a list built from `site.related_posts` would be a list of recent posts under a misleading heading.

The repository's layouts give the agent the shape. `_layouts/post.html` prints the title, the content in `.entry`, then a `.date` div and the Disqus include; `index.html` loops `site.posts` with `post.excerpt` and a Read More link; `_config.yml` sets `permalink: /:title/`, lists `jekyll-sitemap` and `jekyll-feed` under `gems` and has no `related_posts` setting. The only post, `_posts/2014-3-3-Hello-World.md`, has `layout` and `title` in its front matter and no `tags`. The agent adds `_includes/related-posts.html`: it loops `site.posts`, skips the current one by `post.url`, and for each of the current page's `tags` checks `post.tags contains tag`; a post that shares at least one tag is appended to a `related` string of URLs separated by a marker, the loop stops at three, and the include renders them as a `<ul>` of titles with dates, under a `Related posts` heading that only appears when the list is not empty. With no tags on the page, or no post sharing one, it falls back to the three most recent other posts, labelled `More posts`, so a blog that never tags still gets a useful block.

The include goes into `post.html` after the content and before the `.date` div, and a `.related` rule joins `style.scss` next to the `.posts` and `.post` rules, reusing `$lightGray` for a top border and `$gray` for the dates from `_sass/_variables.scss`. The agent adds `tags:` to the Hello World post's front matter with one tag so the first real post has an example, and a line in the README's features list. It does not add `site.related_posts` anywhere, and the pull request explains why, with the sentence from Jekyll's documentation.

Then it builds as the README says, with the `github-pages` gem installed in its own sandbox and `jekyll build`, which brings Jekyll 3.10.0, the version GitHub Pages runs. One post cannot show a related list, so the agent copies the site to a scratch directory, adds six posts with overlapping tags and one with none, builds the copy and reads the generated pages: a tagged post lists the posts sharing its tags and not the others, the untagged post shows the `More posts` fallback, and no page lists itself. It serves the scratch build and opens two of the pages in its own browser. The committed site keeps its one post.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a related posts section to the posts of this Jekyll blog, which is hosted on GitHub Pages without a Gemfile, so plain Liquid only and no LSI. Read _config.yml, index.html, _layouts/post.html, _layouts/default.html, style.scss, _sass/_variables.scss, _posts, .gitignore and the README first. Add an _includes/related-posts.html that lists up to three other posts sharing at least one tag with the current post, newest first, and falls back to the three most recent other posts when there is no match; never list the current post. Include it in the post layout after the content, add a rule to style.scss using the existing Sass variables, add a tags line to the existing post, and note the feature in the README. Do not use site.related_posts. Install the github-pages gem, build the site, build a scratch copy with several tagged posts and one untagged post to show both the match and the fallback, open two pages in a browser, and open a pull request with the commands and their output.",
  "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

The pull request adds `_includes/related-posts.html` and changes `_layouts/post.html`, `style.scss`, `_posts/2014-3-3-Hello-World.md` and the README. Its description quotes the `jekyll build` output for the real site and the scratch copy, the rendered related list from a tagged post and the fallback list from the untagged one, a table of which scratch posts matched which, and a screenshot. `_config.yml` does not change.

A reviewer checks the heading text, the limit of three, whether the fallback should be shown at all on an untagged blog, and the tag added to the first post. After merging, every post with tags gets its matches on the next GitHub Pages build, and adding tags to older posts is the only ongoing work.

## Run it on every Jekyll blog in the terminal

A developer with `jekyll serve` running sends this body from their own machine with the blog in `resources`, keeps writing, and opens the pull request from the console when the webhook on their API key reports the run finished. A team that runs several blogs sends one request per repository, each carrying a `request_id` that is a UUID v5 of the repository's full name, so running the script twice returns the runs already started rather than opening a second pull request on each.

Each run reads its own blog: one whose posts already carry `categories` instead of `tags` gets the include written against that field, and one with a Gemfile and a `--lsi` build step gets a note that `site.related_posts` would work there and the choice left to the reviewer.

## Why run it on Rush?

The tempting one-line answer, `site.related_posts`, is wrong on this host, and the right answer is a loop whose edge cases only show with real posts: a post that lists itself, a tag match that counts the same post twice, a fallback that appears when it should not. The agent builds a scratch copy with enough tagged and untagged posts to hit each case in its own sandbox, with the same gem set GitHub Pages uses, reads the generated HTML and keeps every command and its output in the run's record, so the pull request shows the lists rather than a template that ought to produce them.

It also respects how the blog is run, with no plugin, no Gemfile and no change to the build, so the site keeps deploying from a push exactly as before. Ten blogs get ten pull requests, each matched to its own front matter and layouts.

## Frequently asked questions

### Why not site.related_posts?

Because without the `--lsi` flag Jekyll fills it with the ten most recent posts, which is what its documentation says, and GitHub Pages never passes that flag. A list of recent posts under a Related heading misleads readers; the tag match is cheap and says what it means.

### My posts have no tags yet. What happens?

Each post shows the `More posts` fallback, the three most recent other posts, so nothing looks broken. As you add `tags:` to front matter the matches take over post by post. The pull request tags the first post as an example.

### Does this slow down the build?

The include loops over `site.posts` once per post, so the cost grows with the square of the post count, which is fine for a personal blog of hundreds of posts. The pull request notes that a blog with thousands should prefer a per-tag page over a per-post list.

### Can it match on categories instead?

Yes. The include compares `page.tags` with `post.tags`, and changing both to `categories` is the only edit. A blog that uses both can check either field, and the agent writes it for whichever the existing posts already use.

## More Jekyll jobs

- [Add a Release Workflow for a Jekyll Theme Gem](https://getrush.ai/run/add-release-workflow/jekyll/)
- [Add Search to a Jekyll Site](https://getrush.ai/run/add-search/jekyll/)
- [Add a Sitemap to a Jekyll Site](https://getrush.ai/run/add-sitemap/jekyll/)

## The same job on other stacks

- [Add Related Posts to a Symfony Blog](https://getrush.ai/run/add-related-posts/symfony/)
- [Add Related Posts to a Wagtail Blog from a Linear Issue](https://getrush.ai/run/add-related-posts/wagtail/)
- [Add Related Posts to a Zola Blog](https://getrush.ai/run/add-related-posts/zola/)

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