All jobs

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

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

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

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

The same job on other stacks

Keep reading