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 with this body:
{
"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"
}
]
}- 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 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add Reading Time to a VitePress Blog (VitePress)
- Add Reading Time to a Wagtail Blog (Wagtail)
- Add Reading Time to a Zola Blog (Zola)