All jobs

Add Reading Time to a VitePress Blog

Yes. An agent computes reading time in your VitePress content loader, shows it beside the date on the index and each post, keeps the RSS feed intact, 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 theme before it adds a number to it. In a blog laid out like vuejs/blog, package.json runs VitePress 1.3.4 with Vue 3.5, Tailwind 3.4 with the typography plugin, feed and gray-matter, under pnpm 9.8. .vitepress/config.ts sets the title, cleanUrls, head tags and buildEnd: genFeed. The posts are fifteen Markdown files under posts/ with title, date, author, gravatar and twitter in front matter. The custom theme in .vitepress/theme is six components and one loader: posts.data.ts calls createContentLoader('posts/*.md', { excerpt: true, transform }) and maps each page to { title, url, excerpt, date: { time, string } } sorted newest first; Home.vue lists those entries with a <Date> and the excerpt; Article.vue finds the current post in the same array by route.path for its date and its previous and next links; Date.vue renders a <time> from Post['date']; Layout.vue chooses between them. genFeed.ts is a second loader with render: true that writes feed.rss after the build. Nothing counts words.

The count belongs in the loader, because the data it returns is computed at build time and inlined for the client, so the pages pay nothing at runtime. The agent adds includeSrc: true to createContentLoader, which puts the raw Markdown in src for each page, strips the front matter with gray-matter (already a devDependency), drops fenced code blocks and HTML tags, splits on whitespace, and records readingTime: { words, minutes } with minutes as Math.max(1, Math.ceil(words / 200)) from a single WORDS_PER_MINUTE constant. The transform keeps returning only the mapped fields, so the Markdown source never reaches the bundle. The Post interface declared in the same file gains the new field, which is what Date.vue and the two views import for their types.

A ReadingTime.vue beside Date.vue renders N min read in the same text-gray-500 dark:text-gray-300 classes. Home.vue shows it after the date in the list, separated by the middle dot the layout already uses in its nav, and Article.vue shows it under the title in the header, using the entry it already looks up for the date. Posts whose body is mostly code read short on purpose: code is excluded from the count, which the agent says in the pull request.

It runs pnpm build and pnpm preview, checks the index and one post, and confirms feed.rss is unchanged, since genFeed.ts has its own loader and is not touched. vue-tsc is not part of this project's scripts, so the type change is checked by the VitePress build itself.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add reading time to this VitePress blog. Read package.json, .vitepress/config.ts, .vitepress/genFeed.ts, every file under .vitepress/theme, index.md and two posts under posts/ first. In .vitepress/theme/posts.data.ts enable includeSrc, strip the front matter with gray-matter, remove fenced code blocks and HTML tags, count words, and add a readingTime field with words and minutes (at least 1, from a single WORDS_PER_MINUTE constant of 200) to each mapped post without shipping the source. Update the Post interface. Add a ReadingTime.vue component styled like Date.vue, show it after the date in Home.vue and under the title in Article.vue. Do not change genFeed.ts. Run pnpm build and pnpm preview, confirm feed.rss is unchanged, and open a pull request that shows the index and one post with the new line.",
  "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 changes .vitepress/theme/posts.data.ts, Home.vue and Article.vue, and adds .vitepress/theme/ReadingTime.vue. Its description shows the index and one post with the new line, lists the counting rules (front matter, code and tags excluded; 200 words a minute; minimum one minute), and notes that feed.rss and genFeed.ts are untouched.

A reviewer builds the branch and reads the numbers against two posts they know, a long release announcement and a short one, to see whether the pace feels right; the constant is one line to change. They check the data loader's return shape in the built bundle to confirm no Markdown source leaked into the client, and that the sort order of the index did not change.

From then on every new post gets its reading time from the same loader with no front matter to fill in.

Run it on every new post

The count is a build-time computation, so a new post needs no run: the loader recomputes it on every pnpm build. Where a run earns its keep is the review: an automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request adds a post, build the site and post its reading time and word count as a review, and say if the post is mostly code" tells the author what the index will show before merge. The trigger adds the pull request after the prompt and fills in nothing else.

A team with several VitePress sites sends this body once per repository from its own server, each POST /o/{org}/sessions naming that repository in resources with a request_id that is a UUID v5 of the repository name, so a retried call returns the run already started. Each run reads its own theme and loader and places the line where that theme shows its dates.

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

Why run it on Rush?

This is a small feature with one real trap, the data loader: compute in the wrong place and every reader downloads the Markdown of every post, or the feed changes without anyone meaning it to. The agent reads the loader and the feed generator, builds the site in its own sandbox, checks what the bundle contains and what feed.rss contains, and keeps that evidence with the pull request.

A reviewer reads one loader change and one component. A publisher with several VitePress blogs runs the same request across all of them at once, each adapted to its own theme.

Frequently asked questions

Does it slow the site down?

No. The count runs inside the content loader at build time and the result is inlined with the rest of the post data, so the browser receives a number, not the Markdown. The loader keeps returning only the mapped fields.

How does it count?

It strips front matter, fenced code blocks and HTML tags, then splits on whitespace and divides by 200 words a minute, rounding up with a minimum of one minute. The constant sits in one place in posts.data.ts.

Will the RSS feed change?

No. genFeed.ts builds the feed from its own loader with render: true, and the pull request leaves it alone; the agent confirms feed.rss is byte-for-byte the same after the build.

What about posts in Chinese or Japanese?

Whitespace splitting undercounts them. The agent notes it in the pull request and can count CJK characters separately with a Unicode script regex if the blog publishes in those languages; this blog's posts are English.

More VitePress jobs

The same job on other stacks

Keep reading