Skip to content
Invisible link to canonical for Microformats

Enable giscus comments on a post

Connect GitHub Discussions and verify one published article

Use this guide for an existing post using layout: default and a GitHub repository you can configure for giscus. You need a public repository with Discussions enabled and the giscus app installed, as described by giscus setup. People posting comments through giscus sign in with GitHub.

Connect giscus

  1. Open giscus setup, select your repository and discussion category, and choose how pages map to discussions. Copy the generated embed script with your actual repository and category identifiers.
  2. In your site repository, create or edit _includes/custom/giscus.html. Paste that generated script into the file and save it. The template includes this file with a comment only; it needs your embed before comments can appear.

  3. In _config.yml, edit the existing comments section, or add it once:

    comments:
  provider: giscus

    Preserve unrelated settings and do not add a second comments section.

  4. Open the post and set this entry between its existing --- lines:

    show_comments: true

    Keep its title, layout, date and other settings. Do not replace the whole front matter block. A provider selection alone does not enable the page.

  5. Save all changes to your publishing branch, wait for Actions to finish, then open the article on your public website.

If you already have giscus discussions, keep their repository, category and page mapping choices unless you intend to change thread matching. Switching providers does not migrate comments between services.

Verify the comments area

Scroll below the article and check that the giscus interface loads. Sign in and, if appropriate, leave a test comment; confirm it appears in the selected repository’s Discussions. On other posts, comments remain controlled by their own front matter or existing defaults.

If nothing appears, check the embed file, comments.provider, the post’s show_comments value and its layout. Check giscus’s setup checks for app access, Discussions/category settings and domain restrictions. Browser blockers or a Content Security Policy can also stop the external embed from loading.

To enable more pages, set show_comments: true on those pages or merge it into an existing appropriate front matter default. For another existing service, use Disqus, Cactus, Welcomments or self-hosted Cusdis. Exact identifiers and constraints remain in the comments reference.