# Add Giscus Comments to a Pelican Blog

Yes. An agent adds giscus to your Pelican theme behind pelicanconf.py settings, keeps the Disqus block for sites that use it, builds the site and opens a PR.

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

## What the agent does

The agent reads the theme before it adds a script tag, because Pelican puts comments in the theme's templates and the settings in `pelicanconf.py`, not in the content. In a site like getpelican/pelican-blog, `pelicanconf.py` sets `THEME = "themes/notmyidea"`, `SITEURL = ""`, `DEFAULT_LANG = "en"`, `DEFAULT_PAGINATION = 5`, a `MARKDOWN` dict with the `toc` and `codehilite` extensions, and no `DISQUS_SITENAME`; `publishconf.py` imports it and sets `SITEURL = "https://blog.getpelican.com"`; the `Makefile` has `html`, `publish` and `upload` targets and `develop_server.sh` serves the output. The vendored theme's `templates/article.html` renders the article inside `<section id="content">` and, when `DISQUS_SITENAME and SITEURL and article.status != "draft"`, a `<div class="comments">` with the Disqus embed keyed on `article.url`; `templates/comments.html` prints a link to `#disqus_thread` under the same setting and is included twice from `index.html`, once for the first article shown in full and once for each summary; `base.html` loads no JavaScript at all. The content is 19 articles, all but one in reStructuredText and most with a `:slug:` field, plus two pages, and the repository has no requirements file, so the agent installs `pelican` and `markdown` itself.

giscus needs four values from giscus.app, the repository, its id, the discussion category and the category id, and the site's repository must be public with Discussions on and the giscus app installed. The agent adds `GISCUS_REPO`, `GISCUS_REPO_ID`, `GISCUS_CATEGORY` and `GISCUS_CATEGORY_ID` to `pelicanconf.py`, empty, with a comment that says where each comes from, and optional `GISCUS_MAPPING`, `GISCUS_THEME` and `GISCUS_LANG` with defaults. In `article.html` it adds a second block, after the Disqus one and under the same `article.status != "draft"` guard, gated on `GISCUS_REPO`, that renders the `https://giscus.app/client.js` script with `data-repo`, `data-repo-id`, `data-category`, `data-category-id`, `data-mapping`, `data-strict="1"`, `data-reactions-enabled="1"`, `data-emit-metadata="0"`, `data-input-position="bottom"`, `data-theme`, `data-lang` from `DEFAULT_LANG`, `crossorigin="anonymous"` and `async`, inside the same `<div class="comments">` so the theme's existing styling applies. `comments.html` gets the same gate so the index keeps its comments link, now to `#comments`.

The mapping is the choice that matters. The agent picks `pathname` as the default: `SITEURL` is empty in the development build and set only in `publishconf.py`, so a mapping on the full URL would make `make html` and `make publish` disagree, while the pathname `/pelican-4.7-released.html` is the same in both because the slug comes from the article's `:slug:` field or, where there is none, from its title, and `data-strict="1"` stops giscus matching one post's discussion to another with a similar title. The pull request explains that a site which renames a slug later moves its discussion with it only if it also edits the discussion title, and that `specific` mapping on `article.slug` is the alternative, one line away.

To check it, the agent runs `pelican content -o output -s pelicanconf.py` with the current release and reads the two warnings the site already prints, one about `LOCALE` and one about feeds without `SITEURL`, so the pull request can say it added none; builds again with placeholder values in the giscus settings and greps the output for `giscus.app/client.js` on article pages and for the link in `index.html`; then serves `output/` and opens an article in its own browser, where the giscus frame shows its own error for the placeholder repository, which is the expected state until the reader fills in the four values. It builds once more with the settings empty to show the templates render exactly as before.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add giscus comments to this Pelican site. Read pelicanconf.py, publishconf.py, the Makefile, the theme's templates (article.html, comments.html, index.html, base.html), its static CSS and a few content files first. Add GISCUS_REPO, GISCUS_REPO_ID, GISCUS_CATEGORY and GISCUS_CATEGORY_ID settings, empty with comments saying they come from giscus.app, and optional mapping, theme and language settings with defaults. In the article template render the giscus script only when GISCUS_REPO is set and the article is not a draft, inside the theme's existing comments container, and keep the Disqus block as it is; update comments.html so the index link works for giscus too. Use pathname mapping with strict matching and explain the choice. Install pelican and markdown, build with the settings empty and with placeholders, grep the output, serve it and open an article in a browser, and 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 `pelicanconf.py`, `themes/notmyidea/templates/article.html` and `templates/comments.html`, and adds a short section to the README on the four values and where giscus.app shows them. Its description quotes the build summary for the empty and the placeholder builds, the rendered comments block from one article, and a screenshot of the article page with the frame in place.

A reviewer fills in the four values from giscus.app, decides between `pathname` and `specific` mapping, and checks that drafts still render without the block. After merging, the next `make publish` carries the script on every published article, and the discussions appear in the repository's Discussions tab under the chosen category.

## 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 theme, names the templates and settings it would change and the mapping it would choose, and posts that as a comment on the issue, where the editor picks the mapping before anything is written. A handler on the team's own server then starts the run that writes the pull request, sending this body with the issue's URL added to `resources` and a `request_id` that is a UUID v5 of the issue id, so a retried start returns the run already started.

A team with several Pelican sites on different themes sends one request per repository, each with its own `resources` entry; each run finds that theme's comment block and puts giscus where that theme puts comments.

## Why run it on Rush?

The work is small and the places it can go wrong are in the theme and the two config files: a block rendered on drafts, a link on the index that points at a Disqus anchor, a mapping that differs between the local build and the published one. The agent reads the templates and both configs, builds the site three ways in its own sandbox and opens the page in a browser, with every command and its output kept in the run's record.

It also leaves the site no worse for anyone not using giscus: the Disqus block stays, the settings default to off, and the build prints the same warnings as before. Ten Pelican sites on ten themes get ten pull requests, each with the block in that theme's own comments container.

## Frequently asked questions

### Why keep the Disqus block?

The theme is vendored into this site, but the same `notmyidea` templates ship with Pelican and other sites copy them. Leaving the Disqus block gated on `DISQUS_SITENAME` means a site that sets both settings would show both, which the pull request points out, and a site that sets neither renders exactly as before.

### Does the comment count on the index work?

No, and the pull request says so. Disqus offered a count script; giscus does not expose one for a list page, so `comments.html` keeps a plain link to the comments section of the article, which is what the theme printed before.

### Where do the four ids come from?

From giscus.app: after you enable Discussions on the repository and install the giscus app, the page's configuration section prints `data-repo-id` and `data-category-id` for the repository and category you choose. The README section the agent adds walks through it, and the settings carry the same names.

### Can the frame follow a dark theme?

The notmyidea theme has no dark mode, so the agent sets `GISCUS_THEME` to `preferred_color_scheme`, which lets giscus follow the reader's system setting. A site with its own toggle changes the setting to a fixed theme or drives the frame from its script.

## More Pelican jobs

- [Show Last-Updated Dates on a Pelican Blog](https://getrush.ai/run/add-last-updated-dates/pelican/)
- [Add Link Checking to a Pelican Blog](https://getrush.ai/run/add-link-checking/pelican/)
- [Add llms.txt to a Pelican Site](https://getrush.ai/run/add-llms-txt/pelican/)

## The same job on other stacks

- [Add Giscus Comments to a Starlight Site](https://getrush.ai/run/add-giscus-comments/starlight/)
- [Add Giscus Comments to a VitePress Blog](https://getrush.ai/run/add-giscus-comments/vitepress/)
- [Add Giscus Comments to a Zola Blog](https://getrush.ai/run/add-giscus-comments/zola/)

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