Hosting a thin static blog on a platform like GitHub Pages has numerous advantages, but also takes away some interactivity. Fortunately, Giscus exists and offers a way to embed user comments on static sites.
Table of contents
Open Table of contents
How Giscus works
Giscus uses the GitHub API to read and store comments made by GitHub users in the Discussions associated with a repository.
Embed the Giscus client-side script bundle on your site, configure it with the correct repository URL, and users can view and write comments when logged into GitHub.
The approach is serverless, as the comments are stored on GitHub and dynamically loaded from there on the client side, making it perfect for a static blog like AstroPaper.
Setting up Giscus
Giscus can be set up easily on giscus.app, but I will outline the process briefly.
Prerequisites
The prerequisites for getting Giscus working are:
- The repository is public.
- The Giscus app is installed.
- The Discussions feature is turned on for your repository.
If any of these conditions cannot be fulfilled, Giscus cannot be integrated.
Configuring Giscus
In most cases, the preselected defaults are suitable, and you should only modify them if you have a specific reason. You can always adjust the configuration later.
You need to:
- Select the right language for the UI.
- Specify the GitHub repository you want to connect, typically the repository containing your statically hosted AstroPaper blog on GitHub Pages.
- Create and set an
Announcementtype discussion on GitHub if you want to prevent people from creating random comments directly on GitHub. - Define the color scheme.
After configuring the settings, Giscus provides a generated <script> tag for the next steps.
Simple script tag
The generated script tag should look like this:
<script
src="https://giscus.app/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-emit-metadata="0"
data-input-position="bottom"
data-theme="preferred_color_scheme"
data-lang="en"
crossorigin="anonymous"
async
></script>
Add the tag to the source code of the site. If you are using AstroPaper and want to enable comments on posts, navigate to src/pages/posts/[...slug]/index.astro and paste it where you want the comments to appear, perhaps underneath the “Share this post” buttons.
AstroPaper uses Astro’s client-side routing, so a script runs only once by default. Add data-astro-rerun to the script tag so comments load again when navigating to another post.
<ShareLinks />
<script
src="https://giscus.app/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-astro-rerun></script>
<hr class="my-8 border-dashed" />
You have now integrated comments into AstroPaper.
React component with light/dark theme
The embedded script tag has a static Giscus configuration, including its theme. Since AstroPaper features a light/dark theme toggle, it is useful for comments to transition between light and dark themes with the rest of the site. A more sophisticated embedding approach is required.
First, install the React component for Giscus:
pnpm astro add react
pnpm add @giscus/react
Then create a Comments.tsx React component in src/components:
import Giscus, { type GiscusProps, type Theme } from "@giscus/react";
import { useEffect, useState } from "react";
const GISCUS: GiscusProps = {
repo: "[ENTER REPO HERE]",
repoId: "[ENTER REPO ID HERE]",
category: "[ENTER CATEGORY NAME HERE]",
categoryId: "[ENTER CATEGORY ID HERE]",
mapping: "pathname",
reactionsEnabled: "0",
emitMetadata: "0",
inputPosition: "bottom",
lang: "en",
loading: "lazy",
};
interface CommentsProps {
lightTheme?: Theme;
darkTheme?: Theme;
}
export default function Comments({
lightTheme = "light",
darkTheme = "dark",
}: CommentsProps) {
const [theme, setTheme] = useState(
() => document.documentElement.dataset.theme
);
useEffect(() => {
const root = document.documentElement;
const observer = new MutationObserver(() => {
setTheme(root.dataset.theme);
});
observer.observe(root, { attributeFilter: ["data-theme"] });
return () => observer.disconnect();
}, []);
return (
<div className="mt-8">
<Giscus theme={theme === "dark" ? darkTheme : lightTheme} {...GISCUS} />
</div>
);
}
This React component wraps the native Giscus component and introduces lightTheme and darkTheme props. AstroPaper sets the current theme as data-theme on the <html> element, so the component watches that attribute and switches between dark and light themes whenever the site theme changes.
The GISCUS config at the top of the file holds the values from giscus.app. Do not specify a theme there if you want the lightTheme and darkTheme props to control the appearance.
To complete the process, add the new Comments component to src/pages/posts/[...slug]/index.astro, replacing the script tag from the previous step:
---
// ...
import Comments from "@/components/Comments";
// ...
---
<ShareLinks />
<Comments client:only="react" />
<hr class="my-8 border-dashed" />
And that’s it!