Skip to content
Get packs

Guide · Open source

How to use giscus: add GitHub Discussions comments to your site

Updated · written with AI from the project's own documentation and checked against our catalogue data

giscus is a commenting widget for websites, such as blogs and documentation sites, that stores every comment as a GitHub Discussion in a repository you choose. This guide explains how it works, what your visitors need, how to get the source code, and where it fits compared with other options. By the end you will know whether giscus suits your site and what the setup involves.

giscusgiscus/giscus · ★ 12.2k · MIT

Quick start

  1. 1Check your audience. Confirm that your readers have GitHub accounts, since visitors must authorize the giscus app or comment on GitHub to take part.
  2. 2Prepare a GitHub repository. Choose the repository where comments will be stored as GitHub Discussions.
  3. 3Clone the source. Run git clone https://github.com/giscus/giscus to get the project code.
  4. 4Configure the mapping. Decide how pages link to discussions, using the URL, pathname, or title, and follow the advanced usage guide for extra settings.
  5. 5Add the widget to your site. Place giscus on your pages, using the component library if you use React, Vue, or Svelte.
  6. 6Moderate on GitHub. Review, edit, or remove comments directly in the GitHub Discussions for your repository.

What giscus does and how it works

When a page with giscus loads, giscus uses the GitHub Discussions search API to find the Discussion linked to that page. The page is matched using a mapping you choose, such as the URL, the pathname, or the page title.

If no matching discussion exists, the giscus bot creates one automatically the first time someone leaves a comment or reaction. Because all data lives in GitHub Discussions, you do not need a separate database.

  • Comments and reactions are stored as GitHub Discussions.
  • Visitors can comment through the giscus app after authorizing it with GitHub OAuth, or comment directly on the Discussion on GitHub.
  • New comments and edits are fetched automatically from GitHub.
  • You moderate comments on GitHub.

Who needs to be able to use giscus

giscus is designed for readers who already have a GitHub account. The README says visitors must authorize the giscus app to post on their behalf, or comment on GitHub directly. Readers without a GitHub account cannot take part in the discussion.

Setup also involves a GitHub repository and the giscus app, so it suits developers and technical site owners more than non-technical ones.

  • Good fit: developers running a blog or docs site, projects whose audience already uses GitHub, and owners who want to moderate on GitHub.
  • Poor fit: audiences without GitHub accounts, non-technical site owners, and sites that need a built-in comment admin panel.

Get the giscus source code

The README lists the install method as cloning the repository. It lists no prerequisites. Clone the repository with the command below, then follow the project's documentation for building and configuring it.

The repository is licensed under MIT and written in TypeScript.

git clone https://github.com/giscus/giscus

Configure giscus for your site

The README points to the project's advanced usage guide for additional configuration, such as allowing specific origins. For React, Vue, or Svelte, it mentions a separate giscus component library.

The README also says giscus supports custom themes, multiple languages, and self-hosting. Check the linked guides for the exact settings, since the README notes that features may change over time.

  • Advanced configuration: see ADVANCED-USAGE.md in the repository.
  • Framework integration: see the giscus component library, mentioned in the README.
  • Self-hosting: see SELF-HOSTING.md in the repository.
  • Translations: the README lists many languages and links to CONTRIBUTING.md for adding localizations.

Move existing comments from utterances or Gitalk

If your site used another system that stores comments as GitHub Issues, such as utterances or Gitalk, the README says you can convert those issues into discussions. After conversion, check that the discussion titles match the correct pages. giscus will then use the discussions automatically.

  • Convert issues to discussions using the GitHub documentation linked in the README.
  • Confirm that each discussion title maps to the right page.

Keep in mind the project's current status

The README includes a note that giscus is still under active development and that GitHub is still developing Discussions and its API. Some features may break or change over time. Plan for occasional updates, and test your setup after changes.

What people use it for

  • Adding comments to a developer blog without setting up a database
  • Adding discussion threads to a project documentation site
  • Letting a GitHub-using community comment on project pages
  • Moderating reader comments through GitHub rather than a separate admin panel

Frequently asked questions

Is giscus free?

The README describes giscus as open source, with no tracking, no ads, and always free. It is released under the MIT licence.

Does giscus need a database?

No. The README says giscus needs no database because all data is stored in GitHub Discussions.

Do my readers need a GitHub account?

To comment through giscus, visitors must authorize the giscus app with GitHub OAuth, or comment on the GitHub Discussion directly. So readers without a GitHub account cannot take part.

How do I moderate giscus comments?

You moderate comments on GitHub, in the Discussions linked to your pages. The README does not describe a separate admin panel.

What is the difference between giscus and utterances?

Both store comments in GitHub, and the README says giscus was heavily inspired by utterances. giscus uses GitHub Discussions, while utterances uses GitHub Issues. The README also explains how to convert existing utterances issues into discussions.

Can I host giscus myself?

Yes. The README says giscus can be self-hosted, and points to SELF-HOSTING.md in the repository for details.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

giscus suits developers who run a blog or docs site, want comments without a database, and have an audience that uses GitHub. It is a weaker choice for readers without GitHub accounts, non-technical site owners, or sites that need a built-in comment admin panel.

Install options & downloads