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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
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
The same job on other stacks
- Add Giscus Comments to an Astro Blog (Astro)
- Add Giscus Comments to a Docusaurus Blog (Docusaurus)
- Add Giscus Comments to an Eleventy Blog (Eleventy)