# 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 Rush](https://cloud.getrush.ai/run/add-giscus-comments/hugo/). Opens 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`

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

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

- [Add i18n to a Hugo Site](https://getrush.ai/run/add-i18n/hugo/)
- [Add Lighthouse CI to a Hugo Docs Site](https://getrush.ai/run/add-lighthouse-ci/hugo/)
- [Check for Broken Links in a Hugo Site's CI](https://getrush.ai/run/add-link-checking/hugo/)

## The same job on other stacks

- [Add Giscus Comments to a Jekyll Site](https://getrush.ai/run/add-giscus-comments/jekyll/)
- [Add Giscus Comments to an mdBook](https://getrush.ai/run/add-giscus-comments/mdbook/)
- [Add Giscus Comments to a MkDocs Material Site](https://getrush.ai/run/add-giscus-comments/mkdocs/)

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