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 with this body:
{
"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"
}
]
}- 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 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add Giscus Comments to a Pelican Blog (Pelican)
- Add Giscus Comments to a Starlight Site (Starlight)
- Add Giscus Comments to a VitePress Blog (VitePress)