Marc Santos avatarMarc Santos@marc-santos

💬 Giscussions

A comments system powered by GitHub Discussions, maintained as a fork of giscus.

This is Giscussions, a fork focused on maintaining upstream compatibility while adding selective fork-specific behavior.

⚠️ This is not the official giscus repository.
For upstream, see: https://github.com/giscus/giscus

✨ Highlights

  • Built on top of giscus (GitHub Discussions-powered)
  • No tracking, no ads, always free
  • No database required, all data lives in GitHub Discussions
  • Supports custom themes and multiple languages
  • Extensively configurable
  • Automatically fetches new comments and edits from GitHub
  • Inline comment and reply editing with localized edit history details
  • Can be self-hosted

Fork-specific additions currently implemented

  • Configurable branding visibility via data-show-branding / showBranding
  • Author labels prefer display names when available, with username fallback
  • Reactions are shown inline in the comment header metadata row
  • Logged-out users can open existing mapped threads via a View on GitHub button
  • Comment and reply authors can edit and delete inline; all visitors can inspect edit history
  • Delete and error flows use custom themed dialogs instead of browser popups
  • Delete confirmation overlays are scoped to the relevant comment/reply area,
    with blur and rounded-corner clipping

🆕 Recent fork changes

2026-04-11

Changed

  • Replace browser confirm/alert popups in delete and error flows with custom themed dialogs

Fixed

  • Improve dialog accessibility (focus trap, escape handling, focus restoration, ARIA semantics)
  • Scope delete overlays to the relevant comment/reply container, including rounded-corner-aware blur

2026-04-08

Added

  • Inline edit and delete actions for discussion comments and replies when permitted
  • Localized edit history popovers with edit counts, timestamps, and separate created markers

Fixed

  • Prevent duplicate mapped discussion creation by retrying lookup with app-scoped access when a user-scoped lookup returns no match
  • Sanitize viewer-specific permission flags when returning app-scoped fallback data

2026-04-06

Added

  • Show a View on GitHub action beside Sign in with GitHub for logged-out users when the mapped discussion already exists

Changed

  • Prefer comment and reply author display names in the UI, with username fallback and secondary handle display when applicable
  • Move discussion reactions into the comment metadata header, next to comment/reply counts
  • Refine header link/typography hierarchy and tighten header-to-content spacing across thread states

Fixed

  • Query author display names through schema-safe GraphQL actor fragments for User and Organization to avoid runtime errors on Actor fields

2026-04-05

Added

  • Configurable branding toggle through data-show-branding and showBranding

⚙️ How it works

When giscus loads, the GitHub Discussions search API is used to find the discussion associated with the page based on a chosen mapping (URL, pathname, <title>, and others).

If no matching discussion is found, a discussion can be created the first time someone comments or reacts.

To comment, visitors authorize the giscus app using GitHub OAuth. When visitors are not signed in and a mapped discussion already exists, giscus shows a View on GitHub button next to Sign in with GitHub so they can open the discussion directly. Alternatively, visitors can comment directly on GitHub.

For self-hosted multi-user setups, make sure your GitHub App installation visibility allows other users to authorize (see SELF-HOSTING.md).

🔗 Relationship to upstream

Configuration

Language

Choose the language giscus will be displayed in. Can't find your language? Contribute a localization.

Repository

Choose the repository giscus will connect to. Make sure that:

  1. The repository is public, otherwise visitors will not be able to view the discussion.
  2. The giscus app is installed, otherwise visitors will not be able to comment and react.
  3. The Discussions feature is turned on by enabling it for your repository.

A public GitHub repository. This repo is where the discussions will be linked to.

Page ↔️ Discussions Mapping

Choose the mapping between the embedding page and the embedded discussion.

giscus will search for a discussion whose title contains the page's pathname URL component.

giscus will search for a discussion whose title contains the page's URL.

giscus will search for a discussion whose title contains the page's <title> HTML tag.

giscus will search for a discussion whose title contains the page's <meta property="og:title"> HTML tag.

giscus will search for a discussion whose title contains a specific term.

giscus will load a specific discussion by number. This option does not support automatic discussion creation.

Avoid mismatches due to GitHub's fuzzy searching method when there are multiple discussions with similar titles. See the documentation for more details.

Discussion Category

Choose the discussion category where new discussions will be created. It is recommended to use a category with the Announcements type so that new discussions can only be created by maintainers and giscus.

When searching for a matching discussion, giscus will only search in this category.

Features

Choose whether specific features should be enabled.

The reactions for the discussion's main post will be shown before the comments.

The "powered by giscus" text will be shown below the comments area.

Discussion metadata will be sent periodically to the parent window (the embedding page). For demonstration, enable this option and open your browser's console on this page. See the documentation for more details.

The comment input box will be placed above the comments, so that users can leave a comment without scrolling to the bottom of the discussion.

Loading of the comments will be deferred until the user scrolls near the comments container. This is done by adding loading="lazy" to the <iframe> element.

Theme

Choose a theme that matches your website. Can't find one that does? Contribute a new theme.

Enable giscus

Add the following <script> tag to your website's template where you want the comments to appear. If an element with the class giscus exists, the comments will be placed there instead.

You have not configured your repository and/or category. The values for those fields will not show up until you fill them out.
<script src="https://comments.joyfuldowntime.com/client.js"
        data-repo="[ENTER REPO HERE]"
        data-repo-id="[ENTER REPO ID HERE]"
        data-category="[ENTER CATEGORY NAME HERE]"
        data-category-id="[ENTER CATEGORY ID HERE]"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-show-branding="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="en"
        crossorigin="anonymous"
        async>
</script>

You can customize the container layout using the .giscus and .giscus-frame selectors from the embedding page.

🚀 Getting started

Use this fork similarly to giscus, but point to your own deployed script endpoint:

<script src="https://your-fork-url/client.js"
	data-repo="OWNER/REPO"
	data-repo-id="REPO_ID"
	data-category="General"
	data-category-id="CATEGORY_ID"
	data-term=""
	data-mapping="pathname"
	data-strict="0"
	data-reactions-enabled="1"
	data-show-branding="1"
	data-emit-metadata="0"
	data-input-position="bottom"
	data-theme="light"
	data-lang="en"
	data-loading="lazy"
	crossorigin="anonymous"
	async>
</script>

For full configuration details, see:

🤝 Contributing

Contributions are welcome, especially for:

  • UX and accessibility improvements
  • Reliability and performance improvements
  • Fork-specific documentation clarity

For upstream-core issues, also consider opening an issue at https://github.com/giscus/giscus.

📌 Notes

  • Fork features are documented conservatively to match implemented behavior
  • Upstream changes may be merged selectively

Giscussions - enhanced for better conversations.

Try it out 👇👇👇