# Add Reading Time to a Hugo Blog

Yes. An agent adds a reading-time line to a Hugo theme's post and list templates behind a site parameter, builds the example site to check it, and opens a PR.

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

## What the agent does

The agent reads the templates before touching them. In a theme like janraasch/hugo-bearblog, `layouts/_default/single.html` prints, for a page of type `blog` that is not a menu entry, an `h1` and a `<time>` whose format comes from `.Site.Params.dateFormat` with `02 Jan, 2006` as the default, then `.Content` and the `post_footer.html` partial with the tags. `layouts/_default/list.html` renders each post as a `<time>` and a link inside `ul.blog-posts`. There is no `.ReadingTime` or `.WordCount` anywhere in `layouts/`, `theme.toml` names `min_version = "v0.110.0"`, and `exampleSite/hugo.toml` documents the theme's parameters, including the commented `dateFormat` and `enablePostNavigator`, which is the pattern a new option should follow.

Hugo already computes the number: every page has `.ReadingTime`, an integer of minutes derived from `.WordCount` at the rate Hugo uses, and `.FuzzyWordCount` beside it. The agent adds a `reading_time.html` partial that prints `{{ .ReadingTime }} min read`, with the singular handled for one minute, and includes it after the `<time>` in both templates inside the same `<i>` so the look matches the date. It is wrapped in `{{ if .Param "showReadingTime" }}`, which reads the page's front matter first and the site's `[params]` second, so a site that upgrades the theme sees no change until it opts in, and a single post can turn it off. `exampleSite/hugo.toml` gets `showReadingTime = true` with a comment in the style of the others, and the README's configuration section gets one line.

The build is the check. `.github/workflows/ci.yml` runs `hugo --minify --gc --destination ../public --source ./exampleSite --themesDir ../.. --baseURL https://janraasch.github.io/hugo-bearblog/` with `peaceiris/actions-hugo@v3.2.1` at the latest Hugo, so the agent runs the same command in its sandbox and reads `public/markdown-syntax/index.html`, the one post in `exampleSite/content/blog/`, to confirm the line appears once on the post and once in the blog list, and not on `bear.md` or `hugo.md`, which are pages, not posts.

Because Hugo has no test runner, the agent adds the assertion to the workflow: a step after the build that greps the rendered post for `min read` and fails if it is missing, and greps the home page to confirm it is absent there. That turns a visual check into one CI already runs on every pull request, and the deploy job that follows it with `peaceiris/actions-gh-pages@v4.1.0` is unchanged.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a reading-time line to this Hugo theme. Read layouts/_default/single.html, layouts/_default/list.html, layouts/_default/baseof.html, layouts/partials/post_footer.html, theme.toml, exampleSite/hugo.toml, exampleSite/content/blog/markdown-syntax.md, README.md and .github/workflows/ci.yml first. Add layouts/partials/reading_time.html that prints .ReadingTime as `N min read` with the singular handled, and include it after the date in single.html and list.html inside the same element so it matches the date's style, behind `.Param \"showReadingTime\"` so sites and single posts can opt in or out. Set showReadingTime = true in exampleSite/hugo.toml with a comment like the other parameters, and document it in README.md. Build the example site with the exact hugo command the CI workflow uses, confirm the line appears on the post and the blog list and not on the pages, add a workflow step that greps the rendered post for the line, and open a pull request with the build output and the rendered 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

The pull request adds `layouts/partials/reading_time.html`, changes `layouts/_default/single.html` and `list.html`, `exampleSite/hugo.toml`, `README.md` and `.github/workflows/ci.yml`. Its description pastes the `hugo` build output and the rendered `<i>` element from the post, so a reviewer sees the exact markup next to the date.

A reader opening a post sees the date and `3 min read` in one italic line; the blog list shows the same beside each title. Sites that use the theme keep their current output until they set `showReadingTime`, and a long post can set it false in front matter without a template override. Nothing is added to the page's CSS or JavaScript, which keeps the theme's no-stylesheets, no-scripts promise from `theme.toml`.

Before merging, a reviewer decides whether the default should be on for the example site only or for every site, checks the wording against the theme's minimal tone, and, for a site with `hasCJKLanguage` set, confirms the count Hugo produces reads sensibly for that content.

## Run it on every theme without a reading-time line

Someone maintaining several Hugo sites starts one run per repository from the terminal: one `POST /o/{org}/sessions` each with that repository in `resources` and a `request_id` that is a UUID v5 of its full name, so a retried call returns the run already started. Each run reads its own layouts: a site that vendors its theme gets the partial in its own `layouts/partials/`, which Hugo prefers over the theme's, one that already prints `.WordCount` gets the minutes beside it, and a multilingual site gets the string through `i18n` with a key per language.

Each run opens its own pull request on its own branch, and `GET /o/{org}/sessions` lists them newest first, so the person who started the batch reads every build result from one place.

## Why run it on Rush?

A template change is judged by rendered HTML, and the mistakes are quiet: a line that appears on the home page because the `blog` type check was skipped, a parameter name that silently reads as false, or a build that passes on an old Hugo and fails on the version CI installs. The agent builds the example site with the workflow's own command in its sandbox, reads the output files, and leaves the grep step so the check repeats on every pull request.

The run keeps every command and its output, so the reviewer sees the build and the rendered snippet without installing Hugo. Several sites can be updated at once, each in its own sandbox, and one that already shows reading time is left with a note rather than a second line.

## Frequently asked questions

### Where does the number come from?

Hugo computes `.ReadingTime` for every page from its word count, so the template reads a value that already exists and adds no build step. The pull request does not change how Hugo counts; a site that sets `hasCJKLanguage` gets Hugo's count for that case.

### Will existing sites change when they update the theme?

No. The partial renders only when `showReadingTime` is true, read through `.Param`, which checks the page's front matter and then the site's `[params]`. A site that does not set it sees today's output. The example site sets it so the demo shows the feature.

### Can one post hide it?

Yes. `showReadingTime = false` in that post's front matter overrides the site value, because `.Param` looks at the page first. That covers a photo post or a link post where the minutes would mislead.

### Why add a grep step to CI instead of a test?

Hugo has no test runner, and the workflow already builds the example site on every pull request. A step that reads the rendered post for the line is the cheapest assertion that fails if a later template edit drops the partial, and it needs no new tool.

## More Hugo jobs

- [Add Related Posts to a Hugo Blog](https://getrush.ai/run/add-related-posts/hugo/)
- [Add Search to a Hugo Site](https://getrush.ai/run/add-search/hugo/)
- [Add Social Cards to a Hugo Site](https://getrush.ai/run/add-social-cards/hugo/)

## The same job on other stacks

- [Add Reading Time to a Jekyll Blog](https://getrush.ai/run/add-reading-time/jekyll/)
- [Add Reading Time to a Pelican Blog](https://getrush.ai/run/add-reading-time/pelican/)
- [Add Reading Time to a VitePress Blog](https://getrush.ai/run/add-reading-time/vitepress/)

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