Using the giscus commenting system on the Astro framework blog.

As an emerging framework, Astro has amazing speed and is relatively easy to build with. However, at this stage, its ecosystem has not yet developed, and most themes do not support comment systems like giscus. This article will briefly explain how to use the giscus comment system on Astro framework blogs.

NOTE
Please note that this article is intended for bloggers with a certain level of knowledge.

IMPORTANT
This comment system works fine when deployed on Vercel, but when deployed on Cloudflare Pages, the comment system may not load properly when accessing an article from the homepage. You may need to refresh the page or directly access the article via its link. Please refer to the details below.

giscus Configuration#

The first step is to configure the target comment storage repository for giscus initialization. Open the giscus official website and, as before, configure a repository to generate the following configuration file:

<script src="https://giscus.app/client.js"
        data-repo="YOUR_REPO_NAME"
        data-repo-id="REPO_ID"
        data-category="Announcements"
        data-category-id="CATEGORY_ID"
        data-mapping="title"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

Save it or keep the webpage open for the next step.

Astro Configuration#

Creating the Comment System Script#

Go back to your editor. Here, we'll use VS Code with the Fuwari theme as an example. Find the components directory under src.

/
├── ...
└── src
    ├── components
    └── ...
...

Create a new file named CommentSection.astro (you can choose any name) in your components directory.

Copy and paste the giscus configuration into the file and save it.

Modifying the Article Page#

Find the Astro file responsible for rendering the article. It should be located in the pages directory (similar to other frameworks, a website is composed of "pages," and one of them displays the articles).

In the Fuwari theme, it should be in src -> pages -> posts -> [...slug].astro. Modify it as follows:

---
import CommentSection from '@components/CommentSection.astro'
---
...
	<!-- Article rendering main element -->
	<div>
		...
		<!-- Last element -->
		<div>
			...
		</div>
		<CommentSection />
	</div>
...

Note: Markdown does not support rendering Astro syntax, so the code block here is set to similar JSX for correct highlighting.
The structure shown here is greatly simplified. In any case, <CommentSection /> should be placed inside the main element for rendering the article, after the last element.

Using the Fuwari theme as an example, it should be placed below the copyright information:

<div>
	...
	
	{licenseConfig.enable && <License ...></License>}
	
	<CommentSection />
</div>

The result should look like this:

Comment Style Display

Performance Optimization#

As a JavaScript script, giscus has a significant performance overhead for a static webpage.

In a controlled test (a complex blog post with 1500 words, accessed directly without going through the homepage), the Lighthouse Mobile Performance scores are as follows:

Without adding the comment system: 77 points

Adding the comment system without optimization: 56 points

Adding the comment system with optimization: 70 points

Optimization is crucial, and the method is actually quite simple. Find the Astro file for the comment component (i.e., the CommentSection.astro file) and add the following at the beginning:

---
export const partial = true
---
<script src="https://giscus.app/client.js"
        ...  // Your giscus settings 
</script>

Speculations and Partial Solutions for Abnormal Display#

NOTE
This section is not a comprehensive guide. Please use your own judgment. Everything mentioned here is speculative.

UPDATE
Update: In some cases, disabling caching may make the comment system work properly on CF Pages (but page transition animations will be missing). However, in most cases, the comment system will not load at all!

On the Vercel platform, you only need to configure the blog site as never cache in Cloudflare.

Here's an example:

Cache Configuration Example

However, this method works perfectly for websites deployed on the Vercel platform.

For websites deployed on Cloudflare Pages, this method may not work, which is quite confusing. Sometimes the comments can be loaded correctly, but the page transition animation disappears. Sometimes the comments cannot be loaded at all.

Here's a speculation:

This blog is configured as a static webpage, rendering all components as HTML. This was the initial design of the theme, and it is now difficult to change it to SSR rendering mode.

Cloudflare treats such webpages as pure static webpages and does not perform a second refresh when entering an article. As a result, the comment module cannot be loaded correctly (disabling caching may solve this issue).

On the other hand, Vercel will perform a reload of dynamic components (such as the giscus module) when entering an article (you can see the browser tab icon spinning after entering the article page), so the giscus script can be loaded correctly.

Overall, Vercel has better compatibility with Astro, so Vercel is the preferred choice for deploying Astro websites. Currently, after binding a domain, websites deployed on Vercel can be accessed directly from mainland China.

You have now completed all the settings and successfully implemented the giscus comment system on Astro framework blogs.