All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

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

Keep reading