# Add Pagination to a Jekyll Blog

Yes. An agent paginates the post list of a Jekyll Now blog with jekyll-paginate, which GitHub Pages ships, builds the site locally with extra posts and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pagination/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 touches the index. In a blog started from barryclark/jekyll-now, `index.html` at the root has a `layout: default` front matter and loops over `site.posts`, printing each post's title, `post.excerpt` and a Read More link, so every post the site will ever have renders on one page. `_config.yml` sets `permalink: /:title/`, lists `jekyll-sitemap` and `jekyll-feed` under a `gems` key, excludes the Gemfile, the README and the CNAME from the build, and carries no `paginate` setting. There is no Gemfile in the repository, because `.gitignore` lists it, and the README's local development section installs everything with `gem install github-pages`, which is the fork-first workflow the project is built around. `_layouts/post.html` shows one post with its date and the Disqus include; `style.scss` styles `.posts` and `.post` and imports `_sass/_variables.scss` for colours.

GitHub Pages builds with its own gem set, and the agent reads the versions page: `github-pages` 232 runs `jekyll` 3.10.0 with `jekyll-paginate` 1.1.0, which GitHub's docs list among the plugins that are enabled by default and cannot be disabled, so a site hosted this way needs no Gemfile change. The Jekyll docs set three rules the agent follows: `paginate` is the number of posts per page and `paginate_path` is where later pages go, with `:num` replaced from 2 upward; pagination only works from an `index.html` file, which this site already has, and not from Markdown; and a `permalink` in that file's front matter breaks it, so none is added. The `paginator` object then carries `posts`, `page`, `total_pages`, `previous_page_path` and `next_page_path`.

The agent changes `index.html` to loop over `paginator.posts` instead of `site.posts` and adds a `pagination` block after the list with a Newer link to `paginator.previous_page_path` and an Older link to `paginator.next_page_path`, each only when the path exists, and a `Page 2 of 3` label from `paginator.page` and `paginator.total_pages`, prefixed with `site.baseurl` as every other link in the templates is. `_config.yml` gets `paginate: 5` and `paginate_path: "/page:num/"`, and the `gems` key becomes `plugins`, the name Jekyll has used since 3.5, with `jekyll-paginate` added to the list so a local `jekyll build` outside GitHub Pages also loads it. `style.scss` gets a `.pagination` rule beside `.posts` using the `$gray` and `$blue` variables from `_sass/_variables.scss`.

Then the agent builds the way the README says to. It installs the `github-pages` gem in its own sandbox, which brings Jekyll 3.10.0 and the plugin, and runs `jekyll build`. The repository has one post, `_posts/2014-3-3-Hello-World.md`, so one page is all a build of the real content can show; the agent copies the site to a scratch directory, adds eleven dated posts under `_posts/`, builds that copy and reads `_site/index.html`, `_site/page2/index.html` and `_site/page3/index.html` to confirm five, five and one post, the Older and Newer links between them, and no `page1` directory, which Jekyll never makes. It serves the scratch build and opens the three pages in its own browser. The committed site keeps its one post, and the README's features list gains a line about pagination.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add pagination to the post list of this Jekyll blog, which is hosted on GitHub Pages without a Gemfile. Read _config.yml, index.html, _layouts/default.html, _layouts/post.html, _includes/meta.html, style.scss, _sass/_variables.scss, _posts, .gitignore and the README first. Change index.html to loop over paginator.posts and add Newer and Older links from paginator.previous_page_path and paginator.next_page_path with a page counter, prefixed with site.baseurl, and do not add a permalink to its front matter. In _config.yml set paginate to 5 and paginate_path to /page:num/, and rename the gems key to plugins with jekyll-paginate added. Add a .pagination rule to style.scss using the existing Sass variables. Install the github-pages gem, build the site with jekyll build, then build a scratch copy with enough extra posts to produce three pages and confirm the post counts and links in _site, serve it and open the pages in the browser. Add a line to the README. 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 changes `index.html`, `_config.yml`, `style.scss` and the README. Its description quotes the `jekyll build` output for the real site and for the scratch copy, lists the generated `index.html`, `page2/index.html` and `page3/index.html` with how many posts each holds, shows the rendered Newer and Older links, and includes a screenshot of the second page. No post and no layout changes.

A reviewer checks the page size, whether `paginate_path` should live under `/blog/` instead of the root, and whether the Read More excerpt should stay on paginated pages. After merging, GitHub Pages rebuilds with the plugin it already ships and the home page shows the newest five posts.

## Run it on every new blog repository

A server that provisions blogs for a team sends this body once per repository, with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried start returns the run already started. The API key's `webhook_url` reports each run as it ends, with the pull request's address in the session, and the person who owns the blog reviews it from the console.

A site that also lists posts by tag or category needs the jekyll-paginate-v2 plugin and a GitHub Actions build, which is a separate run with its own prompt.

## Why run it on Rush?

Pagination is easy to get subtly wrong, with a `permalink` that silently disables it, a Markdown index that never paginates, or a `page1` link that leads nowhere, and the way to be sure is to build with enough posts to need three pages. The agent installs the same gem set GitHub Pages uses in its own sandbox, builds the real site and a scratch copy, reads the generated files, opens them in a browser and keeps every command and its output in the run's record.

The change respects how this site is built: no Gemfile, the `github-pages` gem, the plugin GitHub enables for every site, and the `site.baseurl` prefix the layouts already use for project pages. Ten blogs on ten Jekyll themes get ten pull requests, each editing that theme's own index.

## Frequently asked questions

### Do I need to add a Gemfile?

No. GitHub Pages builds with the `github-pages` gem, whose version 232 ships `jekyll-paginate` 1.1.0 and enables it for every site, and the README's `gem install github-pages` gives you the same set locally. The plugin is named in `plugins` so a plain `jekyll build` outside that gem loads it too.

### Why rename gems to plugins?

Jekyll renamed the setting in 3.5 and GitHub Pages runs Jekyll 3.10.0, so `plugins` is the current name and `gems` is the old one. The two existing entries, `jekyll-sitemap` and `jekyll-feed`, move across unchanged.

### Why does the first page have no page1 directory?

Jekyll writes page one to `index.html` at the root and starts `:num` at 2, which the Jekyll docs spell out. The Newer link on page 2 points at `/` for that reason, through `paginator.previous_page_path`.

### Can I paginate tag or category pages too?

Not with this plugin; it pages through posts only. The Jekyll docs point at jekyll-paginate-v2 for tags, categories and collections, and note that GitHub Pages does not support it, so such a site builds with GitHub Actions and pushes the output instead.

## More Jekyll jobs

- [Add Reading Time to a Jekyll Blog](https://getrush.ai/run/add-reading-time/jekyll/)
- [Add Related Posts to a Jekyll Blog](https://getrush.ai/run/add-related-posts/jekyll/)
- [Add a Release Workflow for a Jekyll Theme Gem](https://getrush.ai/run/add-release-workflow/jekyll/)

## The same job on other stacks

- [Add Pagination to a Koa REST API](https://getrush.ai/run/add-pagination/koa/)
- [Add Pagination to a Prisma Query](https://getrush.ai/run/add-pagination/prisma/)
- [Add Pagination to a Quarkus REST API](https://getrush.ai/run/add-pagination/quarkus/)

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