# Add Giscus Comments to a MkDocs Material Site

Yes. An agent adds a Giscus comments partial to your MkDocs Material site, syncs it with the light and dark palette, enables it per page, builds, and opens a PR.

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

## What the agent does

The agent reads the site's configuration before it writes a template. In a documentation site laid out like encode/httpx, `mkdocs.yml` uses the `material` theme with `custom_dir: docs/overrides`, a two-entry `palette` (the `default` scheme for light and `slate` for dark, each with a lightbulb toggle that follows `prefers-color-scheme`), `repo_url` pointing at the GitHub repository, a `nav` of about twenty pages under Introduction, QuickStart, Advanced, Guides, API Reference and Community, the `admonition`, `codehilite` and `mkautodoc` Markdown extensions, and `extra_css` of `css/custom.css`. `requirements.txt` pins `mkdocs==1.6.1`, `mkdocs-material==9.6.18` and `mkautodoc==0.2.0`. The overrides directory holds one file, `partials/nav.html`, which copies the theme's navigation partial to add a sponsor logo under the nav list, so the site already overrides a partial and the pattern is established. `scripts/docs` runs `mkdocs serve`, `scripts/build` runs `python -m build`, `twine check` and `mkdocs build`, and `.github/workflows/test-suite.yml` runs that build script on Python 3.9 to 3.13 for every pull request, so a broken template fails CI.

Material has a documented hook for this: a `partials/comments.html` override, rendered at the end of every page, that the theme ships empty. The agent creates `docs/overrides/partials/comments.html` with the whole block wrapped in `{% if page.meta.comments %}`, an `h2` with the theme's translated comments heading, and the Giscus `script` tag loading `https://giscus.app/client.js` with `data-repo`, `data-repo-id`, `data-category`, `data-category-id`, `data-mapping="pathname"`, `data-reactions-enabled`, `data-emit-metadata`, `data-input-position`, `data-lang` and a `data-theme`. Mapping on `pathname` means a page keeps its discussion when its title changes, which matters for a site whose headings are edited often.

Because the site has a light and a dark scheme, the agent adds the palette-sync script from Material's own guide below the Giscus tag: on load it reads the stored `__palette` and sets `data-theme` to `transparent_dark` when the scheme is `slate` and `light` otherwise; after `DOMContentLoaded` it listens for `change` on `[data-md-component=palette]` and posts a `setConfig` message to the `.giscus-frame` iframe at `https://giscus.app`, so toggling the lightbulb re-themes the comments without a reload. The two ids Giscus needs are the repository's node id and the discussion category's id; the agent opens giscus.app in its browser, enters the repository, and copies the ids the configuration tool produces. When the tool reports that Discussions are off or the Giscus app is not installed on the repository, the agent leaves clearly marked placeholders and says in the pull request which two settings the reader must turn on first.

Comments are opt-in by front matter. The agent adds `comments: true` to the pages under Advanced and Guides, where questions tend to land, and leaves `index.md`, the API reference and the Community pages without it; the pull request lists the choice and the one-line change to use a `.meta.yml` with the `meta` plugin to cover a whole folder instead. It runs `mkdocs build --strict` in the sandbox, serves the site, opens a page with comments and one without in its browser in both schemes, and keeps screenshots of the four states.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Giscus comments to this MkDocs Material site. Read mkdocs.yml, requirements.txt, every file under docs/overrides, docs/css/custom.css, scripts/docs, scripts/build and .github/workflows/test-suite.yml first. Create docs/overrides/partials/comments.html wrapped in a page.meta.comments check, with the Giscus script (data-repo, data-repo-id, data-category, data-category-id, pathname mapping, data-lang) and Material's palette-sync script that sets transparent_dark for the slate scheme and posts setConfig to the giscus iframe on palette change. Open giscus.app in the browser, enter the repository and copy the repo and category ids it produces; if Discussions or the Giscus app are not enabled, leave marked placeholders and say what to enable. Add comments: true to the front matter of the Advanced and Guides pages only. Run mkdocs build --strict, serve the site, check a page with comments and one without in both schemes, and open a pull request that lists the pages with comments and quotes the build 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 `docs/overrides/partials/comments.html` and adds a front-matter block to each page under `docs/advanced/` and the Guides pages (`async.md`, `http2.md`, `logging.md`, `compatibility.md`, `troubleshooting.md`). Nothing in `mkdocs.yml` or `requirements.txt` changes, because the theme already renders the partial and Giscus is a script, not a Python package. The description quotes `mkdocs build --strict`, shows the four screenshots, and either names the ids it copied from giscus.app or lists the two repository settings still to enable.

A reviewer checks the ids against the repository's Discussions category, decides whether the chosen pages are the right ones to open to comments, and reads the partial once to confirm it renders nothing on pages without the flag. The reviewer can preview the result with `scripts/docs` on the branch.

From then on a question under a page lands in a GitHub Discussion that the maintainers already watch, and turning comments on for a new page is one line of front matter.

## Run it on every documentation site repository

A team with several Material sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own site: one with a single palette gets the partial without the sync script, and one with `custom_dir` set to another directory gets the partial there.

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds a page under docs/advanced or the Guides, check that its front matter sets comments and post a review" runs once per pull request. The trigger adds the pull request after the prompt and fills in nothing else. Only work by an owner, member or collaborator fires it.

## Why run it on Rush?

This change is small and mostly configuration, which is exactly where mistakes hide: a partial that renders on every page, a dark comments box on a light page, or ids copied from the wrong repository. The agent builds the site in strict mode, opens real pages in both schemes in its own browser, reads the ids from giscus.app rather than guessing them, and keeps the screenshots and every command with the pull request.

A reviewer reads one partial and a list of pages. A team that maintains documentation for several packages starts the same request across all of them at once.

## Frequently asked questions

### Do I need a new plugin or dependency?

No. Material renders `partials/comments.html` on every page and the override lives in the `custom_dir` the site already has, so `requirements.txt` stays as it is. Giscus itself is a script loaded from giscus.app.

### Why map discussions to pathname?

The alternatives key on the page title or an `og:title`, both of which change when a heading is edited and would orphan the discussion. The URL path of a documentation page is far more stable, and the pull request says what to do if a page is moved.

### Will the comments follow the dark toggle?

Yes. The sync script reads the stored palette on load and posts a `setConfig` message to the Giscus iframe when the palette changes, so the box switches between `light` and `transparent_dark` with the rest of the page, which the screenshots in the pull request show.

### What has to be set on GitHub?

Discussions must be enabled on the repository and the Giscus GitHub App installed on it, and a discussion category chosen. The agent reads the resulting ids from giscus.app's configuration tool; if either setting is missing it leaves marked placeholders and the pull request names both.

## More MkDocs jobs

- [Add i18n to a MkDocs Site](https://getrush.ai/run/add-i18n/mkdocs/)
- [Show Last Updated Dates on MkDocs Pages](https://getrush.ai/run/add-last-updated-dates/mkdocs/)
- [Add Link Checking to an MkDocs Site](https://getrush.ai/run/add-link-checking/mkdocs/)

## The same job on other stacks

- [Add Giscus Comments to a Pelican Blog](https://getrush.ai/run/add-giscus-comments/pelican/)
- [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/)

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