All jobs

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 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'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 with this body:

{
  "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.

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

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

The same job on other stacks

Keep reading