# Add Related Posts to a Hugo Blog

Yes. An agent adds a related posts list under each post of a Hugo Bear Blog site using Hugo's related content index on tags, builds the example site and opens a PR.

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

## What the agent does

The agent reads how the theme renders a post before it adds a list to it. In a site on the Bear Blog theme, as in janraasch/hugo-bearblog, `layouts/_default/single.html` shows the title and date only when `.Type` is `blog`, prints the content, then renders `layouts/partials/post_footer.html`, which includes `post_navigator.html` when the `enablePostNavigator` param is on and lists the post's tags from `.GetTerms "tags"`. `post_navigator.html` links `.PrevInSection` and `.NextInSection` with a struck-out label when there is none, which is navigation by date, not by subject. `exampleSite/hugo.toml` sets `disableKinds = ["taxonomy"]` with `ignoreErrors = ["error-disable-taxonomy"]`, so tag term pages still render at `/blog/:slug` while the taxonomy index does not, and `archetypes/blog.md` gives every new post a `tags` list prefilled from the site's existing terms. `layouts/_default/list.html` renders posts as a `ul` with the class `blog-posts`, which `style.html` styles, and that is the markup the new list reuses.

Hugo builds related content from front matter. Its default configuration, which the agent copies into `exampleSite/hugo.toml` as a `[related]` table because a `related` section must spell out every setting, has `threshold = 80`, `includeNewer = false`, `toLower = false` and three indices: `keywords` with weight 100, `date` with weight 10 and `tags` with weight 80. The agent sets `includeNewer = true`, so a post written last year links to this year's post on the same tag, and keeps the three indices, which means a post with `keywords` in its front matter ranks those matches above tag matches. The template side is one call, `site.RegularPages.Related .`, which the Hugo docs document with `first 5`; the agent uses `first 3` and a `relatedPosts` param to set the count.

The agent adds `layouts/partials/related_posts.html`, which calls `site.RegularPages.Related .` limited by `.Param "relatedPosts"`, and renders a heading and a `ul` with the class `blog-posts` whose items carry the date in a `time` element formatted with the site's `dateFormat` param, as `list.html` does, and the post's `.LinkTitle` linked to `.RelPermalink`. `post_footer.html` includes it inside the same `blog` type guard that wraps the navigator, and only when `relatedPosts` is set, so sites that do not opt in render exactly what they render today. The `[params]` section of `exampleSite/hugo.toml` gets a commented `relatedPosts = 3` entry next to `enablePostNavigator`, and the `[related]` table goes at the end of the file.

Then the agent builds. It installs the Linux build from the v0.169.0 Hugo release, the current one, and runs `hugo --minify --gc --destination ../public --source ./exampleSite --themesDir ../..`, the command from `.github/workflows/ci.yml`. The example site has one post, `markdown-syntax.md` with the tags `markdown` and `syntax`, so a build alone cannot show a related list; the agent copies the example site to a scratch directory, adds three posts with `hugo new blog/<name>.md`, two sharing the `markdown` tag and one with none, builds the copy and confirms that the post page lists the two and not the third, and that `includeNewer` makes the older posts link forward. The committed example site changes only in `hugo.toml`. `npm test` runs `js-beautify -r` over `layouts/**/*.html`, so the agent runs it to format the partial and a README paragraph under Content & structure explains the param and the weights.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a related posts list under each blog post of this Hugo site, which uses the Bear Blog theme. Read exampleSite/hugo.toml, layouts/_default/single.html, layouts/_default/list.html, layouts/partials/post_footer.html, layouts/partials/post_navigator.html, layouts/partials/style.html, archetypes/blog.md, .github/workflows/ci.yml, package.json and the README first. Add layouts/partials/related_posts.html that calls site.RegularPages.Related on the current page, limits it to the relatedPosts param, and renders the results as a ul with the blog-posts class with each post's date and title, matching list.html. Include it from post_footer.html only for pages of type blog and only when relatedPosts is set. Add a commented relatedPosts param and a full [related] table with includeNewer true and the default keywords, date and tags indices to exampleSite/hugo.toml. Install Hugo, build the example site with the command from ci.yml, then verify the list on a scratch copy with a few extra posts sharing tags, run npm test to format the templates, and add a README paragraph. 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 adds `layouts/partials/related_posts.html` and changes `layouts/partials/post_footer.html`, `exampleSite/hugo.toml` and the README. Its description quotes the `hugo` build output for the example site, shows the rendered list from the scratch copy with the posts it linked and the one it left out, and explains the `threshold`, `includeNewer` and index weights it chose. `single.html`, `list.html` and `style.html` have no diff.

A reviewer checks the count, whether `includeNewer` should stay on, and whether `keywords` should outrank `tags` for this site; each is one value in `hugo.toml`. After merging, a site that uses the theme as a submodule turns the list on by adding `relatedPosts` and the `[related]` table to its own config.

## Run it on every new blog repository

A server that provisions blogs 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 blog reviews it from the console.

A site with several content sections, say `blog` and `notes`, gets one run per section, each adding the include behind that section's own type guard.

## Why run it on Rush?

Related content is a question about configuration and front matter together, and the way to answer it is to build and read the output. The agent installs Hugo in its own sandbox, builds the example site with the repository's own CI command, builds a scratch copy with enough posts to exercise the index, and keeps every command and its output in the run's record, so the pull request shows which posts linked to which and why.

The change follows the theme as written: the `blog` type guard, the `.Param` pattern behind `enablePostNavigator`, the `blog-posts` markup `style.html` already styles, and the `js-beautify` formatting `npm test` enforces. Ten blogs on ten Hugo themes get ten pull requests, each placing the list where that theme renders a post.

## Frequently asked questions

### Does this need a plugin or JavaScript?

No. Related content is built into Hugo; `site.RegularPages.Related` reads the index Hugo builds from front matter at build time and the partial renders plain HTML. The theme's no-JavaScript feature stays true.

### Why copy the whole default related configuration into hugo.toml?

Because Hugo's docs say a `related` section replaces the defaults rather than merging with them, so a config that only set `includeNewer` would drop the `keywords`, `date` and `tags` indices. The pull request includes all three with their default weights and changes only `includeNewer`.

### What if two posts share no tags?

Then the `date` index, with weight 10, is the only thing left and the `threshold` of 80 keeps such a match out, so the list is empty and the partial renders nothing. Adding a `keywords` list to the front matter of posts you want paired is the way to connect them without a shared tag.

### My site uses the theme as a submodule. What do I change?

Put `layouts/partials/related_posts.html` and a copy of `post_footer.html` with the include in your site's own `layouts/` directory, which Hugo reads before the theme's, and add `relatedPosts` and the `[related]` table to your `hugo.toml`. The submodule stays untouched.

## More Hugo jobs

- [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/)
- [Add JSON-LD Structured Data to a Hugo Documentation Site](https://getrush.ai/run/add-structured-data/hugo/)

## The same job on other stacks

- [Add Related Posts to a Jekyll Blog](https://getrush.ai/run/add-related-posts/jekyll/)
- [Add Related Posts to a Symfony Blog](https://getrush.ai/run/add-related-posts/symfony/)
- [Add Related Posts to a Wagtail Blog from a Linear Issue](https://getrush.ai/run/add-related-posts/wagtail/)

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