# Giscus — GitHub Discussions-Powered Comments for Any Website

> A lightweight commenting system that uses GitHub Discussions as the backend, so comments live alongside your code.

## Install

Save in your project root:

# Giscus — GitHub Discussions-Powered Comments for Any Website

## Quick Use
```html
<!-- Add to your page (configure at giscus.app) -->
<script src="https://giscus.app/client.js"
  data-repo="YOUR/REPO"
  data-repo-id="YOUR_REPO_ID"
  data-category="Announcements"
  data-category-id="YOUR_CATEGORY_ID"
  data-mapping="pathname"
  crossorigin="anonymous"
  async>
</script>
```

## Introduction
Giscus turns GitHub Discussions into a comment system for blogs, documentation sites, and any static page. Visitors authenticate with their GitHub account, and every comment is stored as a Discussion reply in your repository.

## What Giscus Does
- Embeds a comment widget on any webpage via a single script tag
- Maps pages to GitHub Discussions using pathname, URL, title, or custom term
- Supports reactions, nested replies, and markdown formatting out of the box
- Provides a configuration tool at giscus.app to generate the embed snippet
- Offers framework components for React, Vue, Svelte, and Web Components

## Architecture Overview
Giscus runs as a Next.js application that proxies requests between the browser widget and the GitHub GraphQL API. The embed widget loads in an iframe, communicating with the parent page via postMessage. Authentication uses GitHub OAuth. All data is stored in GitHub Discussions, meaning there is no separate database to manage.

## Self-Hosting & Configuration
- Use the hosted version at giscus.app with zero setup, or self-host the Next.js app
- Enable GitHub Discussions on the target repository before configuring
- Visit giscus.app to generate the embed script with your repo and category settings
- Customize theme, language, and input position via data attributes on the script tag
- For self-hosting, deploy the Next.js app and set the GitHub OAuth app credentials

## Key Features
- No separate database needed; GitHub Discussions is the storage backend
- Full markdown and emoji reaction support matching the GitHub experience
- Lazy loading by default so it does not affect initial page load performance
- Multiple mapping strategies (pathname, URL, title, custom) for flexible routing
- Built-in dark and light themes with custom CSS support

## Comparison with Similar Tools
- **Disqus** — SaaS with ads and tracking; Giscus is free, open source, and ad-free
- **Utterances** — uses GitHub Issues instead of Discussions; Giscus supports nested replies
- **Remark42** — self-hosted with its own database; Giscus leverages GitHub as the backend
- **Commento** — self-hosted and privacy-focused; Giscus requires no server infrastructure

## FAQ
**Q: Do commenters need a GitHub account?**
A: Yes. Authentication is via GitHub OAuth, so commenters must have a GitHub account.

**Q: Can I migrate from Utterances?**
A: Yes. GitHub provides a tool to convert Issues to Discussions, and Giscus has a migration guide.

**Q: Does it affect my site's performance?**
A: The widget loads lazily and asynchronously, adding minimal overhead to page load times.

**Q: Can I moderate comments?**
A: Yes. Comments are GitHub Discussions, so you can moderate them directly in your repository.

## Sources
- https://github.com/giscus/giscus
- https://giscus.app

---
Source: https://tokrepo.com/en/workflows/asset-eea5e994
Author: AI Open Source