# Add Reading Time to a Pelican Blog

Yes. An agent adds a reading time line to a Pelican blog's article template with Jinja's wordcount filter, no plugin needed, builds the site and opens a PR.

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

## What the agent does

The agent reads the theme before it decides between a plugin and a template. In a site laid out like getpelican/pelican-blog, `pelicanconf.py` sets `THEME = "themes/notmyidea"`, so the theme is in the repository and editable, with `DEFAULT_PAGINATION = 5`, a `MARKDOWN` dict that enables the `toc`, `meta`, `admonition` and `codehilite` extensions, and no `PLUGINS` setting. `publishconf.py` imports it and sets `SITEURL` to the real host. `themes/notmyidea/templates/article.html` extends `base.html`, prints the title and, inside `.entry-content`, includes `article_infos.html` before `article.content`; that include is a `<footer class="post-info">` with the date in an `<abbr class="published">`, the author, the category and the tag list. `index.html` lists articles with the same include. The `Makefile` builds with `pelican content -o output -s pelicanconf.py` under `make html` and with `publishconf.py` under `make publish`, and there is no requirements file, so the agent installs the current Pelican, 4.12.0, and Markdown 3.11.2 for the `.md` posts.

The plugin route exists but is the weaker one. `pelican-readtime`, at 0.2.1 on PyPI, adds `readtime` and `readtime_string` attributes to each article from a `READTIME_WPM` setting, but it is enabled through a `PLUGINS = ['readtime']` list rather than the `pelican.plugins` namespace, and Pelican's documentation says that naming a `PLUGINS` list turns off automatic discovery of every namespace plugin, which a blog that later adds one would trip over. Jinja's built-in `wordcount` filter does the counting without any of that, so the agent adds a `reading_time.html` template to the theme that takes the article, computes `article.content | striptags | wordcount`, divides by a words-per-minute value, rounds up with `round(0, 'ceil') | int` and prints `n min read` with a minimum of one.

The words-per-minute value is a setting, because Pelican's documentation says settings from the configuration file are passed to the templates, so `READING_TIME_WPM = 200` in `pelicanconf.py` is readable as `READING_TIME_WPM` in the template with a default in the macro for sites that never set it. The include goes into `article_infos.html` after the date, so the article page and the index list both show it, and `themes/notmyidea/static/css/main.css` gains a rule for the new class beside the existing `.post-info` rules. The `striptags` step matters: `article.content` is rendered HTML, and a post full of release-note links, like the `pelican-4.7.rst` entry with a GitHub link per bullet, would otherwise count every `href` as words.

Then the agent builds. It runs `make html` and `make publish` in its own sandbox, reads `output/index.html` and an article page for the new line, and compares two articles: `content/news/pelican-3.0.rst`, a long release announcement, and `content/pages/not-found.rst`, which is a page and not an article, to confirm pages are untouched. It serves `output` on a local port and opens an article in its own browser. The build log must show no new warnings, since the `toc` Markdown extension and reStructuredText articles both pass through the same template.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add an estimated reading time to the articles of this Pelican site using Jinja filters rather than a plugin. Read pelicanconf.py, publishconf.py, the Makefile, develop_server.sh, the content directory and every template under the theme's templates directory first. Add a template that strips HTML from article.content, counts words with wordcount, divides by a READING_TIME_WPM setting with a default of 200, rounds up and prints n min read with a minimum of 1; include it in article_infos.html after the date so articles and the index both show it, leave pages alone, add the setting to pelicanconf.py and a CSS rule to the theme's stylesheet. Install the current Pelican and Markdown, run make html and make publish, confirm the line on the index and on a long article and its absence on a page, open an article in a browser, and 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 adds `themes/notmyidea/templates/reading_time.html` and changes `themes/notmyidea/templates/article_infos.html`, `themes/notmyidea/static/css/main.css` and `pelicanconf.py`. Its description quotes the `make html` and `make publish` output, the rendered `.post-info` block of a short and a long article with their minutes, the word counts the filter produced for each, and a screenshot. No content file changes.

A reviewer checks the words-per-minute constant, whether the index should show the line or only the article page, and the wording. After merging, `make upload`, which the README names as the publish step, serves the line with the next deploy and no plugin has to be installed on the machine that builds.

## Run it on every Pelican site in the terminal

A developer with `make devserver` running sends this body from their own machine with the site in `resources` and reads the pull request from the console when the webhook on their API key reports the run. A team with several Pelican sites sends one request per repository, each with a `request_id` that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.

Each run reads its own theme: a site that uses a theme installed from a package rather than one in the repository gets the template through a `THEME_TEMPLATES_OVERRIDES` directory, and one that already lists `PLUGINS` gets a note that `pelican-readtime` would also fit.

## Why run it on Rush?

A reading time is a small feature with a wrong default waiting in it: the plugin that silently turns off namespace plugin discovery, a count of rendered HTML rather than text, a page template that inherits a line meant for articles. Each shows only in a build, so the agent installs Pelican in its own sandbox, builds with both configurations, reads the generated HTML for an article, the index and a page, and keeps every command and its output in the run's record.

It also keeps the site the way it is built, with a theme edit and one setting rather than a dependency, so the deploy step in the Makefile does not change. Ten Pelican sites with ten themes get ten pull requests, each placing the line in that theme's article metadata block.

## Frequently asked questions

### Why not the pelican-readtime plugin?

It works, but it is enabled through a `PLUGINS` list, and once that list exists Pelican stops discovering namespace plugins on its own, which the documentation says and which a site adding `pelican-sitemap` later would hit. Jinja's `wordcount` filter does the arithmetic with no dependency, so the pull request uses it and names the plugin as the alternative.

### Will it count reStructuredText and Markdown articles the same way?

Yes. Both are rendered to HTML by the time `article.content` reaches a template, and the filter strips the tags before counting, so the format of the source file does not matter. The pull request shows the count for an `.rst` and an `.md` article.

### Does the summary on the index count or the full article?

The full article. `article_infos.html` receives the article object on the index too, so `article.content` is the whole text even where the list shows `article.summary`, and the number on the index matches the one on the article page.

### Can I change the speed per language?

The setting is one number for the site. A multilingual site can read `article.lang` in the template and pick a value from a dict in `pelicanconf.py`, since settings are passed to templates, and the pull request shows that variant in a comment.

## More Pelican jobs

- [Add Search to a Pelican Blog](https://getrush.ai/run/add-search/pelican/)
- [Add a Sitemap to a Pelican Site](https://getrush.ai/run/add-sitemap/pelican/)
- [Add Structured Data to a Pelican Blog](https://getrush.ai/run/add-structured-data/pelican/)

## The same job on other stacks

- [Add Reading Time to a VitePress Blog](https://getrush.ai/run/add-reading-time/vitepress/)
- [Add Reading Time to a Wagtail Blog](https://getrush.ai/run/add-reading-time/wagtail/)
- [Add Reading Time to a Zola Blog](https://getrush.ai/run/add-reading-time/zola/)

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