All jobs

Add Giscus Comments to a Jekyll Site

Yes. An agent adds a giscus comments section under each post of your Jekyll site on the Minima theme, matched to the theme's skin, builds the site, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the theme already handles comments. In a site on the Minima theme, or in the theme repository jekyll/minima itself, _layouts/post.html renders the article and then, only when jekyll.environment is production, either a "Comments have been disabled for this post" notice when the post's front matter sets comments: false or the _includes/comments.html partial. That partial is Disqus and nothing else: it checks site.disqus.shortname, writes a disqus_thread div, and loads embed.js from the shortname's Disqus host. README.md documents it under "Enabling comments (via Disqus)", _config.yml carries no comments key at all, and _sass/minima/_layout.scss styles only the disabled-comments message. The example post 2016-05-20-my-example-post.md sets comments: false, which is the one existing test of the switch. The theme's _config_theme-dev.yml names six skins, classic, dark, auto and three solarized ones, and script/cibuild builds the example site with that file and packages the gem, which .github/workflows/ci.yaml runs on Jekyll 3.9 and 4.2.

giscus stores comments in GitHub Discussions and needs three things the site owner gets from giscus.app once: the repository, its data-repo-id, and a discussion category with its data-category-id, which exist only after Discussions is turned on and the giscus GitHub App is installed on that repository. The agent does not invent those values. It adds a giscus block to _config.yml, commented like the theme's other optional keys, with repo, repo_id, category, category_id and optional mapping, lang and reactions_enabled, and rewrites _includes/comments.html so that it renders the Disqus block when site.disqus.shortname is set and the giscus block when site.giscus.repo is set, in that order, so an existing Disqus site changes nothing by upgrading.

The giscus block is the standard <script src="https://giscus.app/client.js"> tag with data-repo, data-repo-id, data-category, data-category-id, data-mapping (default pathname, so a post keeps its discussion when its title changes), data-strict="0", data-reactions-enabled, data-emit-metadata="0", data-input-position="bottom", data-lang, crossorigin="anonymous" and async. The theme is the one judgement call: the agent maps Minima's minima.skin onto data-theme, preferred_color_scheme for auto and solarized, dark for dark and solarized-dark, and light otherwise, so a site on the adaptive skin gets comments that follow the reader's system setting. It leaves the production guard and the comments: false branch in post.html exactly as they are.

The check is the build. The agent runs script/cibuild, which builds the example site and packages the gem, then builds once more with JEKYLL_ENV=production and a second config file that fills in placeholder giscus values, and reads the built post pages under _site/ to confirm the script tag appears on posts and is absent from the example post that disables comments. It updates the README section to describe both providers and adds a line under the Minor Enhancements heading of History.markdown, which is where the theme records every change.

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 Jekyll site on the Minima theme. Read _layouts/post.html, _includes/comments.html, _config.yml, _config_theme-dev.yml, README.md, History.markdown, script/cibuild and .github/workflows/ci.yaml first. Add a commented giscus block to _config.yml with repo, repo_id, category, category_id, mapping, lang and reactions_enabled, and say in the comment that the ids come from giscus.app after Discussions is enabled and the giscus app is installed. Rewrite _includes/comments.html to render Disqus when site.disqus.shortname is set, otherwise giscus when site.giscus.repo is set, using the standard giscus client.js script tag with data-mapping defaulting to pathname. Map minima.skin to data-theme: preferred_color_scheme for auto and solarized, dark for dark and solarized-dark, light otherwise. Keep the production guard and the comments: false handling in post.html unchanged. Run script/cibuild, then build again with JEKYLL_ENV=production and a config that fills in placeholder giscus values, and confirm the script tag is on posts and absent from the post that disables comments. Update the README comments section and add a History.markdown entry. Open a pull request that 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 changes _includes/comments.html, _config.yml, README.md and History.markdown, and nothing under _layouts/ or _sass/. Its description quotes the script/cibuild output on both Jekyll versions, lists the config keys it added with what each one does, and pastes the rendered script tag from one built post so the reviewer sees the attributes without opening _site/.

A reviewer checks that the Disqus branch still wins when a shortname is set, that the giscus branch renders nothing when site.giscus.repo is empty, and that the skin mapping matches how their site is configured. The one thing only they can do is fill in the real repo_id and category_id from giscus.app in their own _config.yml; until then the block renders with empty ids and giscus shows its own configuration error instead of comments.

Readers of a deployed site see a comment box and reactions under each post, signed in through GitHub, with the discussion created in the chosen category the first time someone comments.

Run it on every new Jekyll site in the organisation

A handler on the reader's own server watches for new repositories whose Gemfile or _config.yml names Jekyll, and sends this body once per site to POST /o/{org}/sessions, naming the repository in resources and a request_id that is a UUID v5 of the repository name so a retried call returns the run it already started. Each run reads that site's own theme and comments partial, so a site that uses a different include, or one that already has utterances, gets a change that fits it rather than this one.

An automation on the theme's Project with a github trigger on pull_request.opened and pull_request.synchronize reads pull requests that touch _includes/comments.html or _layouts/post.html. An automation's run is read-only, so it posts a review comment when a change would drop the production guard or the comments: false branch, and pushes nothing.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The change is small and the ways to get it wrong are quiet: a partial that renders in development and floods a local preview with a live widget, a theme attribute that ignores the dark skin, a Disqus site that silently switches provider. The agent builds the site on both supported Jekyll versions in its own sandbox, reads the generated HTML, and attaches the output to the pull request, so the review is about the Liquid, not about whether it was built.

For a company with several documentation and blog sites on Jekyll, the same request runs against each of them at once, each in its own sandbox, and each pull request matches that site's theme and config instead of one copied snippet.

Frequently asked questions

Where do data-repo-id and data-category-id come from?

From the configurator at giscus.app, after Discussions is enabled on the repository and the giscus GitHub App is installed there. They are GitHub node ids, not names, so the agent cannot derive them from the repository and leaves them as documented config keys for the site owner to fill in.

Will comments show up in local previews?

No. post.html includes the comments partial only when jekyll.environment is production, and the pull request keeps that guard. bundle exec jekyll serve builds in the development environment, so the widget never loads locally unless you set JEKYLL_ENV=production on purpose.

What about the posts that set comments: false?

Unchanged. The branch that prints the disabled-comments notice sits in post.html above the include, and the agent's production build confirms the example post that uses it still renders the notice and no script tag.

Does the comment box follow the dark skin?

Yes. The partial maps minima.skin to giscus's data-theme: the adaptive skins get preferred_color_scheme, the dark ones get dark, and the rest get light. A site that wants a specific giscus theme can set giscus.theme in _config.yml and the partial uses that instead.

Can a site keep Disqus?

Yes. The partial checks site.disqus.shortname first, so a site that sets it keeps rendering Disqus and never sees the giscus block. Removing the shortname and adding the giscus keys is the whole migration.

More Jekyll jobs

The same job on other stacks

Keep reading