# Add Tag Pages to a Jekyll Blog

Yes. An agent tags your posts, adds a tag page per tag with jekyll-archives, a tag index and the Actions build the plugin needs, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-tag-pages/jekyll/). 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 before it adds anything, because tag pages touch the posts, the layouts, the styles and the build. In a Jekyll site like poole/poole, the `Gemfile` lists `jekyll`, `jekyll-gist`, `jekyll-paginate` and `jekyll-seo-tag`, `Gemfile.lock` resolves Jekyll 4.0.0, and `_config.yml` names those three plugins, sets `paginate: 1` and `permalink: pretty`. The four posts under `_posts/` carry only `layout: post` and `title` in their front matter, with no `tags` line. `_layouts/post.html` prints the title, a `post-date` line and the content, then a related-posts block, `_layouts/default.html` wraps everything with the masthead, and `_includes/head.html` ends with `{% seo title=false %}`. `archive.md` already groups posts by month with `group_by_exp`, which is the closest thing the site has to a browsing page. `styles.scss` imports the partials under `_sass/`, where `_posts.scss` styles `.post-title` and `.post-date`. The only workflow, `.github/workflows/release-notes.yml`, drafts release notes; nothing builds the site in CI.

Tags first. The agent reads each post and adds a `tags` list to its front matter from what the post is about, so the Jekyll introduction post gets `jekyll` and `getting-started`, the content sample gets `markdown` and `examples`, and the options post gets `theming` and `dark-mode`; the pull request lists every assignment so the author can rename them. `_layouts/post.html` gets a `.post-tags` line under the date that loops over `page.tags` and links each to `/tag/{{ tag | slugify }}/`, and a new `_sass/_tags.scss`, imported from `styles.scss`, styles the line in the same gray as `.post-date` using the variables in `_sass/_variables.scss`, so it follows the dark scheme the options post describes.

The pages per tag come from the jekyll-archives plugin, since Jekyll generates no page for a tag on its own. The agent adds `gem "jekyll-archives"` to the `Gemfile`, runs `bundle install` so the lock resolves the current 2.x release, which accepts Jekyll 3.6 through 4, and adds the plugin to the `plugins` list in `_config.yml` with a `jekyll-archives` block: `enabled: [tags]`, `layouts: {tag: tag}` and `permalinks: {tag: '/tag/:name/'}`. A new `_layouts/tag.html` extends `default` and renders `page.title`, which the plugin fills with the tag name, and loops over `page.posts` in the same markup `index.html` uses for a post entry. A `tags.md` page lists `site.tags` sorted by name with a post count each, linking to the generated pages, and the masthead gains no link because the archive page is where the site already sends readers to browse, so `archive.md` gets a line pointing at it.

The build is the catch. GitHub Pages' built-in Jekyll build runs the `github-pages` gem with a fixed plugin list, and `jekyll-archives` is not on it, so a site deployed that way would silently build without tag pages. The agent checks for a Pages workflow, finds none in this repository, and adds `.github/workflows/pages.yml`: `ruby/setup-ruby` with `bundler-cache: true`, `bundle exec jekyll build` with `JEKYLL_ENV=production`, `actions/upload-pages-artifact` and `actions/deploy-pages`, with the `pages: write` and `id-token: write` permissions those need. In its sandbox it runs `bundle exec jekyll build --strict_front_matter`, checks that `_site/tag/jekyll/index.html` and `_site/tags/index.html` exist, runs `bundle exec jekyll doctor`, and opens a post in its browser to see the tag line link through to the right page.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add tag pages to this Jekyll blog. Read Gemfile, Gemfile.lock, _config.yml, every file under _posts, _layouts, _includes and _sass, index.html, archive.md and .github/workflows first. Add a tags list to each post's front matter based on its content and list every assignment in the pull request. Show the tags under the date in _layouts/post.html, linking each to /tag/<slug>/, with styles in a new _sass partial imported from styles.scss. Add the jekyll-archives gem and plugin with enabled tags, a tag layout and the permalink /tag/:name/, a _layouts/tag.html that lists page.posts, and a tags.md index page listing site.tags with counts. Because GitHub Pages' built-in build does not load jekyll-archives, add a GitHub Actions Pages workflow that runs bundle exec jekyll build and deploys the artifact if no such workflow exists. Run bundle exec jekyll build --strict_front_matter and jekyll doctor, confirm the generated tag pages exist, and open a pull request with the 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 changes `Gemfile`, `Gemfile.lock`, `_config.yml`, `_layouts/post.html`, `styles.scss`, `archive.md` and each post's front matter, and adds `_layouts/tag.html`, `tags.md`, `_sass/_tags.scss` and `.github/workflows/pages.yml`. Its description quotes the `jekyll build` and `jekyll doctor` output, lists the generated `_site/tag/*/index.html` paths, and shows a screenshot of a post with its tag line and of one tag page, from the run's record.

A reviewer reads the tag assignments first, since those are editorial, then the workflow, which is the one change that affects how the site deploys: after merge the site builds from the Actions run rather than the Pages default, and the repository's Pages setting must point at GitHub Actions as the source, which the pull request says in one line. The layouts, the styles and the archive page are small diffs that read in a minute.

## Run it on every Linear issue labelled blog

In the console, add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `blog` label. When an issue such as "readers cannot find all the posts about theming" gets the label, the trigger puts the issue after the prompt, and the run reads which tags the issue asks for before assigning any. Only label changes by a person in your Rush org fire it, and the automation starts at most `max_runs_per_hour` runs in an hour.

An automation's runs are read-only, so the run that pushes the branch starts from your own server: a handler receiving the automation's comment sends this body to `POST /o/{org}/sessions` with the issue URL in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered event returns the run already started.

## Why run it on Rush?

Tag pages on Jekyll are easy to half-do: the links render, the pages never generate, and nobody notices until the deploy. The agent runs the real build in its own sandbox, looks for the generated files by path, opens the pages in a browser, and keeps the commands and screenshots in the run's record, so the pull request carries proof that the pages exist rather than a template that should produce them.

The build question is the part a laptop skips. Whether a site deploys from the Pages default or from Actions decides whether the plugin runs at all, and the agent reads the workflows directory, adds the workflow only when none exists, and says in the pull request what setting has to change after merge.

## Frequently asked questions

### Why a plugin at all? Jekyll already knows site.tags.

`site.tags` lets a single page list every tag, which the new `tags.md` does, but Jekyll writes no page per tag. jekyll-archives generates one file per tag at the permalink you set, each rendered with your layout and given `page.title` and `page.posts`, which is what a link under a post needs to land on.

### Does it work on GitHub Pages?

Not with the default build, which loads only the plugins in the `github-pages` gem; jekyll-archives is not one of them. Deploying from a GitHub Actions workflow that runs `bundle exec jekyll build` removes that limit, which is why the agent adds one when the repository has none, and the same workflow works for any other plugin you add later.

### Who decides the tags?

The agent proposes them from each post's content and lists every assignment in the pull request. Tags are editorial, so the author renames or removes them in the front matter before merging, and the generated pages follow whatever the posts say on the next build.

### What happens to a tag with a space or a capital letter?

jekyll-archives slugifies tag names for the permalink by default, so `Dark Mode` becomes `/tag/dark-mode/`, and the post layout links with the same `slugify` filter so the two always match. `slug_mode` in the plugin block changes the rule if you need a different one.

### Can categories get the same treatment?

Yes. Adding `categories` to the plugin's `enabled` list and a `category` layout generates `/category/<name>/` pages the same way. The pull request keeps to tags because the posts have no categories, and says where the two lines go.

## More Jekyll jobs

- [Add a Typo Check to a Jekyll Site in CI](https://getrush.ai/run/add-typo-check/jekyll/)
- [Add Author Pages to a Jekyll Blog](https://getrush.ai/run/add-author-pages/jekyll/)
- [Add Dark Mode to a Jekyll Site](https://getrush.ai/run/add-dark-mode/jekyll/)

## The same job on other stacks

- [Add Tag Pages to a Gatsby Blog from a Linear Issue](https://getrush.ai/run/add-tag-pages/gatsby/)

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

- [Add Tailwind CSS to a Leptos App](https://getrush.ai/run/add-tailwind/leptos/)
- [Add TanStack Query to an Expo App](https://getrush.ai/run/add-tanstack-query/expo/)

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