# Add Pagination to a Wagtail Blog Index

Yes. An agent paginates your Wagtail blog index and tag archive like the site's other indexes, keeps the fragment cache correct per page, and opens a pull request.

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

## What the agent does

The agent reads the index pages that already paginate before touching the one that does not. In a Wagtail site like wagtail/bakerydemo, `BreadsIndexPage` in `bakerydemo/breads/models.py` and `PersonIndexPage` in `bakerydemo/people/models.py` each have a `paginate(self, request)` method wrapping Django's `Paginator` with 12 items per page, catching `PageNotAnInteger` and `EmptyPage` to clamp to the first and last page, and their templates include `includes/pagination.html`, which renders previous, numbered and next links from a `subpages` variable using `?page=` query strings. `BlogIndexPage` in `bakerydemo/blog/models.py` does neither: `get_context` puts every live `BlogPage` ordered by `-date_published` into `posts`, and the `tag_archive` route, a `RoutablePageMixin` view at `tags/<slug>/`, renders the same `blog/blog_index_page.html` with an unordered `posts` queryset from `get_posts`. `requirements/base.txt` pins Wagtail 8.0 and Django 6.0.

The template has one detail that decides the design. `blog_index_page.html` wraps the post loop in `{% wagtailcache 500 posts tag %}`, a fragment cache keyed on the queryset and the tag. If pagination were added without changing that key, the second page would be served the cached first page for 500 seconds. So the agent adds a `paginate` method to `BlogIndexPage` mirroring the breads one, orders the tag archive by `-date_published` as the index already is, passes the page object as `posts` from both `get_context` and `tag_archive`, and changes the cache key to include `posts.number` so each page caches separately. Below the list it includes `includes/pagination.html` with `subpages=posts` inside an `{% if posts.has_other_pages %}` block, the same markup the breads template uses, so the CSS already in `static/css/main.css` applies with no new styles.

Because the tag archive is served from a routable sub-URL, the `?page=2` links the include generates stay relative to `/blog/tags/<slug>/`, so paging within a tag works without a template change to the include. The page size is 12 like the other indexes unless the issue asks otherwise. No model field changes, so no migration is created and `manage.py makemigrations --check --noinput`, which `.github/workflows/ci.yml` runs, stays clean. The `api_fields` on `BlogIndexPage` and `BlogPage` are untouched, so the headless API keeps its shape.

Tests go in a new `bakerydemo/blog/tests/` package, where `AGENTS.md` says render tests belong, in the style of `bakerydemo/base/tests/test_home_page.py`: a `WagtailPageTestCase` with `setUpTestData` that creates a `Site`, a `BlogIndexPage` and thirteen `BlogPage` children with dates and one shared tag, rather than loading the full demo fixture. The tests assert 12 cards on the first page and one on the second, that `?page=99` clamps to the last page, that `?page=abc` renders the first, that the tag archive paginates and keeps its path, and that the second page's content differs from the first even with the cache warm. The agent runs the suite with `DJANGO_SETTINGS_MODULE=bakerydemo.settings.test`, as `AGENTS.md` recommends and CI does, then `make lint-server`, which is `ruff format --check`, `ruff check`, `curlylint` and `djhtml --check` on the templates, and opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Do the work the Linear issue describes: paginate the blog index of this Wagtail site. Read requirements/base.txt, bakerydemo/blog/models.py, bakerydemo/breads/models.py, bakerydemo/people/models.py, bakerydemo/templates/blog/blog_index_page.html, bakerydemo/templates/breads/breads_index_page.html, bakerydemo/templates/includes/pagination.html, bakerydemo/base/tests/test_home_page.py, bakerydemo/settings/test.py, Makefile, ruff.toml, AGENTS.md and .github/workflows/ci.yml first. Add a paginate method to BlogIndexPage that mirrors the one on BreadsIndexPage, 12 posts per page with PageNotAnInteger and EmptyPage handled the same way, and use it in both get_context and the tag_archive route, ordering the tag archive by -date_published like the index. In blog_index_page.html include includes/pagination.html with subpages=posts when posts.has_other_pages, and change the wagtailcache key so it includes the page number as well as posts and tag, so page two is never served the cached page one. Do not change any model field, api_fields or the pagination include. Add bakerydemo/blog/tests/test_blog_index.py as a WagtailPageTestCase with setUpTestData creating a site, a blog index and thirteen posts with one shared tag, asserting twelve on page one and one on page two, clamping for page=99 and page=abc, the tag archive paginating on its own path, and distinct content on page two with the cache warm. Run env DJANGO_SETTINGS_MODULE=bakerydemo.settings.test ./manage.py test, ./manage.py makemigrations --check --noinput and make lint-server, fix what they report, and open a pull request.",
  "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 result is a pull request on its own branch touching `bakerydemo/blog/models.py`, `bakerydemo/templates/blog/blog_index_page.html` and a new `bakerydemo/blog/tests/test_blog_index.py`, with no migration and no change to the shared include or the stylesheet. The description explains the cache key change in two sentences, states the page size and why it matches the breads and people indexes, and notes that the tag archive is now ordered by date like the index.

The transcript keeps the Django test run under the test settings, the `makemigrations --check` result, and the `ruff`, `curlylint` and `djhtml` output from `make lint-server`. `GET /o/{org}/p/{project}/sessions/{id}/changes` returns the three-file diff for review in your own tooling.

A reviewer checks that the `wagtailcache` key includes the page number, that `paginate` is called in both the index and the tag archive so the two views cannot drift, and that the test for a warm cache really renders page one before page two. A follow-up on the same session can add the pagination to the home page's blog section, which lists `featured_section_3.specific.children` sliced to six in `base/home_page.html`, if the team wants it there too.

## Run it on every Linear issue labelled agent

Add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled` with the label your editors or developers use for agent work. The labelled issue is appended after the prompt, so an issue that asks for nine posts per page, or for pagination on the locations index as well, steers the run with no change to the prompt. A label set by an app integration never fires the trigger, and `max_runs_per_hour` caps how many runs the automation starts in an hour.

From your own server, send `POST /o/{org}/sessions` with the repository and the issue URL, `https://linear.app/<workspace>/issue/<ID>`, in `resources`, read through your Linear connection, with a `request_id` that is a UUID v5 of the issue id so a redelivered webhook returns the run already started. A `webhook_url` on the key receives `run.completed` with `data.session_url` when the pull request is open.

## Why run it on Rush?

Pagination on a Wagtail index is a small change with one trap, the fragment cache keyed without the page number, that no unit test of the `Paginator` catches and that only shows up as readers seeing page one twice in production. The agent reads the template, spots the `wagtailcache` tag, changes the key and writes the warm-cache test, in a sandbox with the project's own test settings where `CACHES` is local memory and the test is deterministic.

The repository's gates run first: the Django tests, the migration check and the four linters in `make lint-server`, all kept in the transcript the pull request links to. Several Wagtail sites can be paginated at once from the same request, each run reading its own templates and includes rather than pasting in a generic one.

## Frequently asked questions

### Why change the wagtailcache key?

Because `{% wagtailcache 500 posts tag %}` caches the rendered list for 500 seconds keyed on the queryset and the tag. Once the list is a page, two different pages would share one cache entry and readers would see page one again at `?page=2`. Adding `posts.number` to the key gives each page its own entry; the test with a warm cache proves it.

### Does it need a migration?

No. Pagination is a method on `BlogIndexPage` and a template change; no field is added, so `./manage.py makemigrations --check --noinput` in CI stays clean and no data is touched.

### Does the tag archive paginate too?

Yes. `tag_archive` is a `RoutablePageMixin` view at `tags/<slug>/` that renders the same template, so it is given the same page object, ordered by `-date_published` like the index, and the `?page=` links from the shared include stay on the tag's own path.

### Will the headless API change?

No. `api_fields` on `BlogIndexPage` and `BlogPage` are not touched, so clients of the Wagtail API see the same fields. Pagination here is for the rendered HTML; the API already pages through its own `limit` and `offset` parameters.

### Why twelve posts per page?

Because `BreadsIndexPage` and `PersonIndexPage` already use 12 and the include renders the same controls, so the three indexes behave alike. The prompt reads the Linear issue, and an issue that asks for a different count changes one number.

## More Wagtail jobs

- [Add Reading Time to a Wagtail Blog](https://getrush.ai/run/add-reading-time/wagtail/)
- [Add Related Posts to a Wagtail Blog from a Linear Issue](https://getrush.ai/run/add-related-posts/wagtail/)
- [Add Request ID Logging to a Wagtail Site](https://getrush.ai/run/add-request-id-logging/wagtail/)

## The same job on other stacks

- [Add Pagination to an aiohttp App](https://getrush.ai/run/add-pagination/aiohttp/)
- [Add Pagination to an Eleventy Blog Archive](https://getrush.ai/run/add-pagination/eleventy/)
- [Add Cursor Pagination to a FastAPI Endpoint from a Linear Issue](https://getrush.ai/run/add-pagination/fastapi/)

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