# Add Giscus Comments to a Zola Blog

Yes. An agent adds a giscus comment thread under each post of your Zola site, configured from config.toml and loaded on post pages only, builds it and opens a PR.

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

## What the agent does

The agent reads the templates before it adds a script to any of them, because on a theme that promises no JavaScript the only acceptable place is one page type. In a site on the Terminimal theme, as in pawroman/zola-theme-terminimal, `templates/index.html` is the base: it imports the theme's macros, renders the head through `head_macros::head`, and leaves five blocks for children, `extra_head`, `header`, `content`, `footer` and `extra_body`, the last one empty at the end of `body`. `templates/page.html` extends it and fills `content` with `post_macros::header`, `post_macros::content` with the full text, and `post_macros::earlier_later`, which renders the previous and next links when `config.extra.enable_post_view_navigation` is on. Every post in `content/` uses that template, and so do the pages under `content/pages/`, which set `path` in their front matter; `archive.md` names its own `archive.html`. `config.toml` carries an `[extra]` table with `accent_color`, `background_color`, `logo_text`, `menu_items` and the navigation prompt, and no comments setting. The README's badge reads `JavaScript: none`, and the theme ships no script at all.

giscus stores each thread as a GitHub Discussion in a repository the reader chooses. Its README explains that the client script searches Discussions for the one matching the page by a chosen mapping, such as the URL or the `pathname`, and that the giscus bot creates the discussion the first time someone comments or reacts; its advanced guide lists `data-strict` for exact title matching and `data-theme`, which takes a built-in theme name or the URL of a CSS file giscus then links into its frame. The values the script needs, the repository, its id, the discussion category and the category id, come from the configuration tool at giscus.app, after the reader has enabled Discussions on a public repository and installed the giscus app on it; none of them is something the run can produce, so they are placeholders the pull request names.

The agent adds a `[extra.giscus]` table to `config.toml` with `enabled`, `repo`, `repo_id`, `category`, `category_id`, `mapping = "pathname"`, `strict = true`, `reactions_enabled = true`, `input_position = "bottom"` and `lang`, and a `templates/partials/giscus.html` that writes the `script` tag with `src="https://giscus.app/client.js"`, one `data-` attribute per setting and `crossorigin="anonymous"`. The theme's colours decide the comment theme: `data-theme` is `light` when `background_color` is `light` or the accent ends in `-light`, `preferred_color_scheme` when either ends in `-auto`, and `dark` otherwise, computed in Tera from the same `config.extra` values `head.html` uses to pick stylesheets. `page.html` includes the partial in the `extra_body` block, guarded by `config.extra.giscus.enabled` and by `page.extra.comments`, which defaults to true for posts and which the agent sets to `false` in the front matter of `content/pages/about.md`, so the about page stays script-free; `index.html`, the archive and tag templates are untouched, so the list pages load nothing. A placeholder `div` with class `giscus` goes under the post navigation, inside the `post` container, so the frame sits where the theme's `.post` margins apply.

Then the agent builds and looks. 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, confirms the script tag appears in each post's HTML with the configured attributes and in none of the list, tag, archive or about pages, then serves `public/` and opens a post in its own browser to see the giscus frame request the placeholder repository, which is as far as a run without the reader's ids can go. The README's badge is left in place and a line under it says the one exception, and a README section explains the four values to fill in and how to turn comments off for one page.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add giscus comments to the posts of this Zola site. Read config.toml, templates/index.html, templates/page.html, templates/macros/head.html, every file under content/ and the README first. Add an [extra.giscus] table to config.toml with enabled, repo, repo_id, category, category_id, mapping, strict, reactions_enabled, input_position and lang, using placeholder values for the ids. Add templates/partials/giscus.html that renders the giscus client script with one data attribute per setting and crossorigin anonymous, choosing data-theme from the theme's accent_color and background_color settings. Include it from page.html's extra_body block only, guarded by the enabled flag and a page.extra.comments front matter key that defaults to true, and set that key to false on the about page. Do not touch index.html or the list, tag and archive templates. Install Zola, run zola build and zola check, confirm the script appears only on post pages, serve the site and open a post in the browser. Add a README section on filling in the ids and disabling comments per page. 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 `config.toml`, `templates/page.html`, `content/pages/about.md` and the README, and adds `templates/partials/giscus.html`. Its description quotes the `zola build` and `zola check` output, lists which generated pages contain the script tag and which do not, shows the rendered tag for one post with its attributes, and names the four values to replace, with the address of the giscus configuration tool. The base template and the list templates have no diff.

A reviewer checks the `mapping` choice, since `pathname` ties each thread to a URL and a renamed post would start a new one, whether `strict` matching is wanted, whether comments should be off by default and on per post instead, which is a one-word change in the guard, and whether the about page is the only page to exclude. 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 block where a script can be added without touching list pages, and posts a comment on the issue with the partial, the configuration table and the pages it would exclude. A handler on the team's server 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 several themes in use across its sections gets one run per template that renders a post, each adding the include in that template's own block.

## Why run it on Rush?

Where the script lands is a question about the theme's template inheritance, and whether it lands only there is a question about the built site; both are answered by building. The agent installs Zola, builds in its own sandbox, searches the generated HTML for the tag page by page, opens a post in a browser and keeps every command and its output in the run's record, so the pull request shows the comments block on posts and its absence everywhere else.

The change respects the theme as written: the one `extra_body` block that `index.html` leaves for children, the `config.extra` colours `head.html` already reads, and the `path` convention that tells posts from pages. Ten blogs on ten themes get ten pull requests, each placing the script in that theme's own block.

## 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 gives the repository id and the category id, which are the placeholder values in `config.toml`; the pull request lists them with where each one goes.

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

On post pages, yes, and nowhere else. The script is included from `page.html`'s `extra_body` block only, so the home page, the archive, the tag lists and any page with `comments = false` in its front matter still load no script. The README gets one line under the badge saying so.

### How does the comment frame match my colour scheme?

The partial picks `data-theme` from the same `accent_color` and `background_color` settings the theme uses for its stylesheets: light variants get the light theme, `-auto` variants follow the visitor's system preference, and the rest get dark. A custom CSS URL also works there, as the giscus advanced guide describes.

### 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 `mapping = "title"` as the alternative for a site that renames posts often, since giscus also matches discussions by page title.

### Can I turn comments off for one post?

Yes. Add `comments = false` under `[extra]` in that post's front matter, which is what the pull request does for the about page. Setting `enabled = false` in `config.toml` turns them off everywhere without removing the partial.

## More Zola jobs

- [Add a Second Language to a Zola Site](https://getrush.ai/run/add-i18n/zola/)
- [Show Last Updated Dates on a Zola Blog](https://getrush.ai/run/add-last-updated-dates/zola/)
- [Add Link Checking to a Zola Site](https://getrush.ai/run/add-link-checking/zola/)

## The same job on other stacks

- [Add Giscus Comments to an Astro Blog](https://getrush.ai/run/add-giscus-comments/astro/)
- [Add Giscus Comments to a Docusaurus Blog](https://getrush.ai/run/add-giscus-comments/docusaurus/)
- [Add Giscus Comments to an Eleventy Blog](https://getrush.ai/run/add-giscus-comments/eleventy/)

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