All jobs

Add Reading Time to a Wagtail Blog

Yes. An agent adds a reading-time property to a Wagtail blog page that counts words across its StreamField blocks, shows it in templates and the API, 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 page model before it counts anything. In a site shaped like wagtail/bakerydemo, requirements/base.txt pins Django>=6.0,<6.1 and wagtail>=8.0,<8.1, runtime.txt and the Dockerfile run Python 3.12, and ruff.toml selects B, BLE, C4, E, F, I, RUF100, T20, UP and W at a line length of 88. bakerydemo/blog/models.py defines BlogPage with introduction, image, a body StreamField of BaseStreamBlock, subtitle, tags, date_published, an authors helper, get_tags, and api_fields that expose each field through APIField. BaseStreamBlock in bakerydemo/base/blocks.py has five block types: heading_block with heading_text and a size, paragraph_block as a RichTextBlock, image_block with caption and attribution, block_quote with text and attribute_name, and embed_block. templates/blog/blog_page.html includes base/include/header-blog.html, which prints the title, subtitle, introduction and date_published inside blog__published, then renders authors and {{ page.body }}. blog_index_page.html lists child pages inside a wagtailcache block. The blog app has migrations and models but no tests; bakerydemo/base/tests/test_home_page.py shows the style, a WagtailPageTestCase with setUpTestData and the nested_form_data and streamfield helpers from wagtail.test.utils.form_data.

The count is a property, not a field, so no migration and no editing is needed. BlogPage.reading_time is a cached_property that walks self.body: for paragraph_block it takes the RichText value's source through django.utils.html.strip_tags, for heading_block the heading_text, for block_quote the text, for image_block the caption, and skips embed_block; it adds introduction, splits on whitespace, divides by a WORDS_PER_MINUTE constant declared at the top of blog/models.py with a comment, rounds up, and never returns less than one minute. A second property, word_count, keeps the raw number for the API and the tests. Because the walk reads the StreamField's own values and not the rendered HTML, it costs no template rendering and no database query beyond the page already loaded.

Display follows the existing markup. header-blog.html gains a blog__reading-time span beside blog__published, so the figure sits with the date on every post, and the post cards in blog_index_page.html show it under the title inside the cached block. The strings use the blocktranslate tag where the surrounding templates already load i18n, and plain text where they do not. api_fields gains APIField("reading_time") and APIField("word_count"), so GET /api/v2/pages/<id>/ returns both to the headless front ends the demo's API router serves.

Tests go in a new bakerydemo/blog/tests.py as a WagtailPageTestCase: it builds a BlogIndexPage and a BlogPage under the root with streamfield([...]) holding a paragraph of known length, a heading, a quote and an image caption, asserts word_count equals the sum and reading_time equals the rounded division, checks that an empty body answers one minute, and renders the page to assert the span is present. Before pushing, the agent runs what .github/workflows/ci.yml runs: make lint-server, which is ruff format --check, ruff check, curlylint --parse-only bakerydemo and djhtml --check on every template, then ./manage.py check, ./manage.py makemigrations --check --noinput, which passes because nothing changed in the schema, and ./manage.py test with DJANGO_SETTINGS_MODULE=bakerydemo.settings.test.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add a reading time to the blog pages of this Wagtail site and open a pull request. Read requirements/base.txt, ruff.toml, Makefile, bakerydemo/blog/models.py, bakerydemo/base/blocks.py, bakerydemo/templates/blog/blog_page.html, bakerydemo/templates/blog/blog_index_page.html, bakerydemo/templates/base/include/header-blog.html, bakerydemo/base/tests/test_home_page.py and .github/workflows/ci.yml first. Add word_count and reading_time cached properties on BlogPage that count words in the introduction and in the paragraph, heading, block quote and image caption blocks of body, divide by a WORDS_PER_MINUTE constant declared at the top of the module, round up and return at least one minute; do not add a model field or a migration. Show the reading time beside the published date in header-blog.html and on the cards in blog_index_page.html, and expose both properties through api_fields. Add bakerydemo/blog/tests.py as a WagtailPageTestCase using the streamfield form-data helper covering the count, the rounding, an empty body and the rendered span. Run make lint-server, manage.py check, manage.py makemigrations --check --noinput and manage.py test with the test settings, and paste the test output in the 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

What comes back is a pull request that edits bakerydemo/blog/models.py, two templates and one include, and adds bakerydemo/blog/tests.py. There is no migration file, and makemigrations --check in the description proves none was needed. The description shows the Django test runner output with the new test class and the make lint-server run passing ruff, curlylint and djhtml.

On a repository with this CI workflow the pull request runs the server lint, the client lint and the test job with uv, and the Docker build workflow builds the image, migrates, loads the initial data and runs the tests again inside the container.

A reviewer checks the WORDS_PER_MINUTE value against what their readership expects, that the count skips embeds and strips rich-text tags rather than counting them, and that the cached block in the index template still renders the figure for each card. Then they merge.

Run it on every new Wagtail site from the template

A team that runs several Wagtail sites sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own StreamBlock definitions, so a site whose body holds a code_block or a table_block gets rules for those, and each opens its own pull request with a test built from that site's own blocks.

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 word count over a StreamField is easy to get wrong in ways a quick look does not catch: rich text counted with its tags, an embed URL counted as words, a quote's attribution counted twice. In a Rush sandbox the agent builds a page from the site's own block types with the Wagtail form-data helpers, asserts the exact count, renders the template, and keeps the test output in the run's record, so the pull request shows the number is right for this site's blocks.

The repository's checks are ruff, curlylint and djhtml on the server side and a Django test run under the test settings, plus a Docker build that loads the demo data. Each run on Rush does all of it in its own sandbox before pushing, and the same request body works on every Wagtail site a team owns.

Frequently asked questions

Why a property and not a field?

A field would need a migration and a save hook to stay correct when the body changes. A cached_property computed from the StreamField is always current for the page as loaded, costs one walk over the blocks, and lets makemigrations --check pass unchanged.

Does it count the rich text's HTML?

No. The paragraph block's value is a RichText, and the count takes its source through strip_tags before splitting, so a link or a bold span counts its words and not its markup. A test with a paragraph that contains a link asserts the number.

Can I change the words per minute?

Yes. WORDS_PER_MINUTE is one constant at the top of blog/models.py with a comment, and the tests compute the expected minutes from it, so changing it does not break them.

Will it show on the API?

Yes. reading_time and word_count are added to api_fields, so the v2 pages endpoint the site's api_router serves returns them for each BlogPage, alongside the existing introduction and body fields.

More Wagtail jobs

The same job on other stacks

Keep reading