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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add Pagination to a Koa REST API (Koa)
- Add Pagination to a Prisma Query (Prisma)
- Add Pagination to a Quarkus REST API (Quarkus)