All jobs

Add Giscus Comments to a Hugo Blog

Yes. An agent adds a giscus thread under each blog post of a Hugo Bear Blog site, configured from hugo.toml and loaded on posts only, builds it 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 starts with the templates, because on a theme whose theme.toml lists no javascript among its features the only defensible place for a script is one page type. In a site on the Bear Blog theme, as in janraasch/hugo-bearblog, layouts/_default/baseof.html is the base: it renders favicon.html, seo_tags.html and style.html in the head, leaves custom_head.html and custom_body.html as empty partials the README says a site overrides from its own layouts/partials directory, and wraps the main block in a header, main and footer. layouts/_default/single.html fills that block for every page: a title and date only when .Type is blog, the content inside a content element, then post_footer.html, which renders post_navigator.html when the enablePostNavigator param is on and the post's tags from .GetTerms "tags". Pages such as bear.md and hugo.md sit at the content root with menu = "main"; posts live under content/blog/, get /:slug/ permalinks from exampleSite/hugo.toml, and the archetypes/blog.md archetype gives them title, date, description and tags.

giscus keeps each thread as a GitHub Discussion in a repository the reader picks. Its site lists three prerequisites, a public repository, the giscus app installed on it and Discussions enabled, and its configuration tool produces a script tag with data-repo, data-repo-id, data-category, data-category-id, data-mapping (pathname by default), data-strict, data-reactions-enabled, data-emit-metadata, data-input-position, data-theme, data-lang, crossorigin="anonymous" and async. The frame renders where the script tag sits, or inside an element with the class giscus when one exists. The repository id and category id are values only the reader can supply, so they are placeholders the pull request names.

The agent adds layouts/partials/giscus.html, which writes the script tag with one data- attribute per setting read from .Site.Params.giscus, and a div with the class giscus so the frame lands under the post's tags rather than at the end of body. It is included from single.html after post_footer.html, inside the same blog type guard the title uses, and only when .Site.Params.giscus.repo is set and the page's comments front matter param is not false. data-theme defaults to preferred_color_scheme, since style.html already switches its colour variables on prefers-color-scheme: dark, so the comment frame follows the same rule as the page. A [params.giscus] table in exampleSite/hugo.toml holds repo, repoId, category, categoryId, mapping, strict, reactionsEnabled, inputPosition, theme and lang, commented like the enablePostNavigator and dateFormat entries above it. A reader whose site uses the theme as a submodule puts the same two files in the site's own layouts/ directory, which Hugo reads before the theme's.

Then the agent builds the way .github/workflows/ci.yml does: 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 ../.. from the repository root. It checks that public/markdown-syntax/index.html, the one post in the example site, contains giscus.app/client.js with the configured attributes, and that public/index.html, public/blog/index.html, public/bear/index.html and public/hugo/index.html do not. npm test runs js-beautify over layouts/**/*.html with -r, so the agent runs it to format the new partial the way the theme's other templates are formatted and commits what it rewrites. The theme.toml feature list is left as it is and a README section under Content & structure explains the four ids, the per-post comments = false switch and that list pages load nothing.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add giscus comments to the blog posts of this Hugo site, which uses the Bear Blog theme. Read theme.toml, exampleSite/hugo.toml, layouts/_default/baseof.html, layouts/_default/single.html, every partial under layouts/partials, archetypes/blog.md, .github/workflows/ci.yml, package.json and the README first. Add layouts/partials/giscus.html that renders the giscus client script with one data attribute per setting from .Site.Params.giscus, crossorigin anonymous and async, plus a div with the class giscus. Include it from single.html after post_footer.html, only for pages of type blog, only when the repo param is set, and skip pages whose comments front matter param is false. Add a commented [params.giscus] table to exampleSite/hugo.toml with placeholder ids and preferred_color_scheme as the theme. Install Hugo, build the example site with the same command as ci.yml, confirm the script appears on the post page and on no list or top-level page, and run npm test to format the templates. Add a README section on the ids and on turning comments off per post. 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/giscus.html and changes layouts/_default/single.html, exampleSite/hugo.toml and the README. Its description quotes the hugo build output, lists which generated pages contain the script tag and which do not, shows the rendered tag for the post with every attribute, and names the four placeholder values with the address of the giscus configuration tool. baseof.html, list.html and the other partials have no diff.

A reviewer checks the mapping choice, since pathname ties a thread to a URL and a renamed post starts a fresh one, whether strict matching is wanted, and whether comments should be off by default and on per post instead, which is a one-word change in the guard. After merging, the reader fills in the ids from giscus.app, and the first comment on a post creates its discussion.

Run it on every Linear issue labelled comments

An automation in the Project that holds the site takes a linear trigger on linear.issue.labeled with the label comments. Its runs are read-only, so the saved prompt asks for a plan: the run reads the templates, finds the partial and the guard it would add, and posts a comment on the issue with the partial, the config table and the pages it would leave untouched. A handler on the team's server then starts the run that writes the pull request, sending this body with the issue's URL in resources and a request_id that is a UUID v5 of the issue id, so a retried start returns the run already started.

A site with more than one theme in its themes/ directory gets one run per theme, each placing the include in that theme's own single template.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Whether the script lands on posts and nowhere else is a question about the built site, and the agent answers it by building. It installs Hugo in its own sandbox, runs the same command the repository's CI runs, searches the generated HTML page by page and keeps every command and its output in the run's record, so the pull request shows the comment block on the post and its absence on the home, blog, Bear and Hugo pages.

The change follows the theme's own conventions: the blog type guard single.html already uses, the .Site.Params pattern behind enablePostNavigator, and the custom_body.html override the README describes for sites that would rather not touch the theme. Ten blogs on ten Hugo themes get ten pull requests, each placing the script where that theme renders a post.

Frequently asked questions

What do I need on GitHub first?

A public repository with Discussions enabled and the giscus app installed on it. The configuration tool at giscus.app then shows the repository id and the category id, which are the placeholder values in [params.giscus]; the pull request lists them with where each one goes.

Does this break the theme's no-JavaScript promise?

On blog posts, yes, and nowhere else. The partial is included from single.html inside the blog type guard, so the home page, the /blog/ list, the tag pages and top-level pages such as Bear and Hugo still load no script. A post with comments = false in its front matter loads none either.

My site uses the theme as a git submodule. Where do the files go?

Into your site's own layouts/ directory: layouts/partials/giscus.html and a copy of layouts/_default/single.html with the include. Hugo reads a site's templates before its theme's, which is the same mechanism the README describes for custom_head.html, so the submodule stays untouched and updates cleanly.

How does the comment frame match dark mode?

The theme's style.html switches its colour variables on prefers-color-scheme: dark, and giscus's preferred_color_scheme theme follows the same media query, so both change together. Any other built-in giscus theme name, or the URL of a CSS file, can go in the theme param instead.

What happens if I rename a post?

With mapping = "pathname", giscus looks for a discussion by the page's path, so a renamed post starts a fresh thread and the old one stays in Discussions. The pull request names title as the alternative for a site that renames posts often, since giscus can match on the page title instead.

More Hugo jobs

The same job on other stacks

Keep reading