# Add Related Posts to a Zola Blog

Yes. An agent adds a related posts block under each post of a Zola site, ranked by shared tags through the tags taxonomy in Tera, builds the site and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-related-posts/zola/). 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's post template and the site's tags before it writes a line of Tera. In a site on the Terminimal theme, as in pawroman/zola-theme-terminimal, `config.toml` declares one taxonomy, `tags`, and `templates/page.html` renders a post through three macros from `templates/macros/post.html`: `header`, which prints the title, date and the post's tags through the `tags` macro, `content`, and `earlier_later`, which links the next and previous posts by date when `config.extra.enable_post_view_navigation` is on, under the prompt in `config.extra.post_view_navigation_prompt`. The five posts in `content/` overlap in subject: `zola-is-nice.md` and `welcome-terminimal-theme.md` share the `zola` tag, `i-dont-like-javascript.md` and `learning-javascript.md` share `javascript`, and `i-dont-like-javascript.md` shares `rant` with `more-ranting.md`. `sass/pagination.scss` styles the earlier and later block with a centred title over a rule and the theme's buttons, which is the look the new block borrows.

Zola has no related content feature, but it exposes what one needs. `get_taxonomy_term(kind="tags", term=...)` returns a term with its `pages`, each a full page with `permalink`, `title`, `date`, `draft` and `taxonomies`, and a page's own tags are at `page.taxonomies.tags`. Tera supports `set_global` inside loops, the `in` test against arrays and the `unique` filter the theme's `tags` macro already uses, which is enough to rank candidates without JavaScript or a plugin.

The agent adds a `related` macro to `templates/macros/post.html`. For each tag of the current post it reads the term's pages, drops the post itself and any draft, and keeps the union of the rest. It then counts, for each candidate, how many of its tags appear in the post's tags, and emits candidates from the highest count down until it has `config.extra.related_posts` of them, keeping each tag term's own date order within a count. The output is a block with the class `related`, a title from `config.extra.related_posts_prompt` over a rule like the pagination title, and a list of links with the date in a `post-date` span and the title. `page.html` calls it after the content and before `earlier_later`, only when `related_posts` is set and the post has tags. `config.toml` gets commented `related_posts` and `related_posts_prompt` entries under `[extra]`, and a new `sass/related.scss`, imported from `sass/style.scss` after `pagination`, reuses the title styles with the `--accent` variables.

Then the agent builds. It installs the Linux build from the v0.23.6 Zola release, the current one, runs `zola build` and `zola check` at the theme's root, where `config.toml` and `content/` make it its own demo site, and reads the output: `public/zola-is-nice/index.html` links the welcome post and nothing else, `public/i-dont-like-javascript/index.html` lists the learning post and the ranting post, and `public/pages/about/index.html`, which has no tags, is unchanged. It serves `public/` and opens a post in its own browser to see the block sit between the text and the earlier and later links. A README section under Configuration explains the two settings and that a post with no tags shows no block.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a related posts block under each post of this Zola site, ranked by shared tags. Read config.toml, templates/index.html, templates/page.html, templates/macros/post.html, every file under content/ and sass/, and the README first. Add a related macro to templates/macros/post.html that, for each tag of the current post, reads the term with get_taxonomy_term, collects its pages without the current post or drafts, counts how many tags each candidate shares with the post, and lists up to config.extra.related_posts of them from most shared tags down, each with its date and title. Give the block a title from config.extra.related_posts_prompt styled like the pagination title. Call it from page.html after the content and before the earlier and later links, only when related_posts is set and the post has tags. Add commented related_posts and related_posts_prompt entries to config.toml and a sass/related.scss imported from style.scss. Install Zola, run zola build and zola check, confirm which posts each post links in the generated HTML and that untagged pages are unchanged, serve the site and open a post in the browser. Add a README section. 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 changes `templates/macros/post.html`, `templates/page.html`, `config.toml`, `sass/style.scss` and the README, and adds `sass/related.scss`. Its description quotes the `zola build` and `zola check` output, lists for each of the five demo posts which posts its block links and with how many shared tags, names the pages whose HTML did not change, and includes a screenshot of the block in the default blue scheme.

A reviewer checks the count, whether a one-tag match is enough to show a post or whether the macro should need two, which is one comparison in the loop, and whether the block belongs above the earlier and later links or below them. After merging, the block appears on every tagged post with no change to content files.

## Run it on every new blog repository

A server that provisions sites for a team sends this body once per repository, with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried start returns the run already started. The API key's `webhook_url` reports each run as it ends, with the pull request's address in the session, and the person who owns the site reviews it from the console.

A site with a second taxonomy, say `categories`, gets a follow-up run that adds it as a second source of candidates with its own weight.

## Why run it on Rush?

Ranking by shared tags is logic in a template language with no debugger, and the way to know it works is to build and read the output for every post. The agent installs Zola in its own sandbox, builds, checks each generated page against the tags in `content/`, opens a post in a browser and keeps every command and its output in the run's record, so the pull request shows which post links which and why.

The change respects the theme as written: the macros file every post template imports, the `config.extra` pattern behind the navigation prompt, the Sass partial list in `style.scss` and the title styles of the pagination block. Ten sites on ten Zola themes get ten pull requests, each placing the block in that theme's own post template.

## Frequently asked questions

### Does this need a plugin or JavaScript?

No. The macro uses `get_taxonomy_term`, `page.taxonomies.tags` and plain Tera loops, all built into Zola, and renders static HTML at build time. The theme's README badge about JavaScript stays true.

### How are the posts ranked?

By how many tags they share with the current post, most first; within the same count they keep the order Zola gives the tag term's pages, which is by date. A post that shares no tag never appears, and a post with no tags of its own shows no block.

### Will this slow down the build?

The macro reads one taxonomy term per tag on each post, which Zola already holds in memory, so the work grows with the number of tagged posts times their tags. The pull request quotes the `zola build` timing for the demo site before and after the change.

### Can I exclude a post from the list?

Drafts are already left out. The pull request names the one-line change that also skips posts with `related = false` under `[extra]` in their front matter, which the macro would read alongside the tags.

## More Zola jobs

- [Add Search to a Zola Site](https://getrush.ai/run/add-search/zola/)
- [Add JSON-LD Structured Data to a Zola Site](https://getrush.ai/run/add-structured-data/zola/)
- [Add a Table of Contents to Zola Posts](https://getrush.ai/run/add-table-of-contents/zola/)

## The same job on other stacks

- [Add Related Posts to an Astro Blog](https://getrush.ai/run/add-related-posts/astro/)
- [Add Related Posts by Shared Tags to an Eleventy Blog](https://getrush.ai/run/add-related-posts/eleventy/)
- [Add Related Posts to a Gatsby Blog](https://getrush.ai/run/add-related-posts/gatsby/)

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