All jobs

Add Blog Categories to a Wagtail Site

Yes. An agent adds a BlogCategory snippet, a chooser on blog pages, a category archive route and listing pills to a Wagtail site, tests it 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 how the blog is already organised before it adds a taxonomy. In a site like wagtail/bakerydemo, requirements/base.txt pins wagtail>=8.0,<8.1 on Django>=6.0,<6.1, and bakerydemo/blog/models.py defines BlogPage with subtitle, introduction, a StreamField body, date_published, authors through BlogPersonRelationship in a MultipleChooserPanel, and tags = ClusterTaggableManager(through=BlogPageTag). BlogIndexPage(RoutablePageMixin, Page) lists live children by -date_published in get_context, serves tags/<slug>/ through a tag_archive route that redirects to the index with a message for an unknown tag, and exposes get_posts(tag) and get_child_tags. templates/blog/blog_index_page.html renders a pill per tag and the posts through includes/card/blog-listing-card.html inside a wagtailcache block keyed on posts and tag; blog_page.html lists the post's tags under the body. bakerydemo/base/wagtail_hooks.py registers Person and FooterText through SnippetViewSet classes grouped in BakerySnippetViewSetGroup, and FooterText carries TranslatableMixin because WAGTAIL_I18N_ENABLED is on in settings/base.py. The blog app's migrations stop at 0008.

Tags are free text; a category is a fixed list an editor picks from, so it becomes a snippet. BlogCategory(TranslatableMixin, models.Model) gets name, a unique slug and an optional description, with panels for the three and a Meta that inherits TranslatableMixin.Meta so the locale constraint holds. BlogPage.categories becomes a ParentalManyToManyField to it, joins the panels after tags with a CheckboxSelectMultiple widget and gets an APIField so the v2 API serialises it; makemigrations blog writes 0009. A new bakerydemo/blog/wagtail_hooks.py registers BlogCategoryViewSet(SnippetViewSet) with list_display of name and slug and search_fields on name, under its own Blog menu item. BlogIndexPage gains a categories/<slug>/ route named category_archive with the same shape as tag_archive, get_posts takes a category argument, and get_child_categories returns the categories in use ordered by name. The index template renders a second pill row for categories, the wagtailcache key grows to include the category, and blog_page.html links each of the post's categories to its archive. Templates go through djhtml because make lint-server runs djhtml --check with ruff format --check, ruff check and curlylint.

bakerydemo/base/tests/test_home_page.py shows the project's test pattern: a WagtailPageTestCase whose setUpTestData builds the page tree once and a Site with hostname testserver. The agent adds bakerydemo/blog/tests/test_categories.py in that shape: an index page, three posts, two categories, one post unpublished. It asserts that the archive URL from index.reverse_subpage('category_archive', args=[slug]) lists only the live posts in that category, that an unknown slug redirects to the index, that the index context carries both categories, and, with nested_form_data, that a BlogPage with categories can be created through the admin form. With DJANGO_SETTINGS_MODULE=bakerydemo.settings.test it runs ./manage.py check, ./manage.py makemigrations --check --noinput, ./manage.py test and make lint-server, the steps in .github/workflows/ci.yml, and fixes what fails before it pushes.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add blog categories to this Wagtail site and open a pull request. Read requirements/base.txt, bakerydemo/blog/models.py, bakerydemo/base/models.py, bakerydemo/base/wagtail_hooks.py, bakerydemo/templates/blog/blog_index_page.html, bakerydemo/templates/blog/blog_page.html, bakerydemo/templates/includes/card/blog-listing-card.html, bakerydemo/base/tests/test_home_page.py, bakerydemo/settings/base.py, Makefile and .github/workflows/ci.yml first. Add a BlogCategory snippet with TranslatableMixin, name, unique slug and description, registered through a SnippetViewSet in a new blog/wagtail_hooks.py. Add categories as a ParentalManyToManyField on BlogPage with a CheckboxSelectMultiple panel and an APIField, and write the migration. Add a categories/<slug>/ route on BlogIndexPage shaped like tag_archive, extend get_posts with a category argument, add get_child_categories, render category pills on the index with the cache key extended, and link each post's categories on the blog page. Run templates through djhtml. Add bakerydemo/blog/tests/test_categories.py as a WagtailPageTestCase covering the archive, an unknown slug, unpublished posts and creating a page with categories. Run manage.py check, makemigrations --check, manage.py test with the test settings and make lint-server, and paste the output in the pull request. Do not change tags or the people snippet.",
  "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

What comes back is a pull request that edits bakerydemo/blog/models.py and the two blog templates, adds bakerydemo/blog/wagtail_hooks.py, migration 0009 and a test module under bakerydemo/blog/tests/, and changes nothing in the base app. The description names the new admin menu item and the archive URL and pastes the check, makemigrations --check, test and lint-server output.

On a repository with the CI and Docker build workflows, the pull request runs lint-server, test-server with the test settings module, and the container build that migrates and loads the initial data, so a migration that did not apply cleanly would fail there.

A reviewer checks that the migration is reversible and carries the translation fields, that the archive excludes drafts the way the tag archive does, that the cache key really changes per category, that the checkbox panel lists the current locale's categories, and that the listing cards prefetch categories rather than querying per card. Then they decide whether categories should also appear in the site search.

Run it on every Wagtail site that needs a taxonomy

A team with several Wagtail sites sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own blog models, so a site without TranslatableMixin gets a plain snippet and a site with a Category already gets the chooser and the archive only, and each run opens its own pull request.

Give the API key a webhook_url and Rush POSTs run.completed when each turn ends, with the session_url to read the pull request and the test output from.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Wagtail taxonomy touches the model, a migration, the admin, routing and templates, and it is only right when all five agree, which means a migrated database and a rendered page. In a Rush sandbox the agent installs requirements/development.txt, builds the SQLite database the test settings expect, runs the suite and the lint target, and keeps every command and its output in the run's record.

The change follows the shapes the site already has: a snippet registered the way Person is, a route shaped like tag_archive, a panel beside tags. The same request works on any Wagtail site with a blog index and child pages.

Frequently asked questions

Why a snippet instead of more tags?

Tags are typed by editors and grow without limit; a category list is fixed, has a slug and a description, and can be managed and translated in one place. The snippet gives editors a checkbox list on the page and the site a stable URL per category.

Does this ship a migration?

Yes, 0009 in the blog app, creating BlogCategory with its translation fields and the many-to-many table for BlogPage.categories. makemigrations --check --noinput, which the CI workflow runs, is clean with it in place.

Does the category list respect the site's locales?

The snippet carries TranslatableMixin, as FooterText does, so each category has a locale and a translation_key and can be translated through the simple translation workflow the site already enables.

Can editors see how many posts each category has?

Not in this change; list_display shows name and slug. A count column is a short follow-up on the SnippetViewSet, and the pull request notes it.

More Wagtail jobs

More jobs like this: Hand off a long task

Keep reading