All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading