giscus Comments Integration

This site is a static Docusaurus site, so comments cannot depend on a local runtime server or database. The current implementation uses giscus and stores page discussions in the separate GitHub Discussions repository NeverGpDzy/docs-comments. The site only loads the comment component on selected pages.

The component is designed to behave like the audio player: it is mounted automatically by layout code. Authors do not need to import or render it inside each Markdown or MDX file. If a page is a blog post page, a Travel doc page, or a custom page explicitly allowed by layout code, the layout renders the comment section automatically.

Current Behavior

Comments appear only on these pages:

Page type	Chinese path	English path	Shows comments
Blog post page	/blog/...	/en/blog/...	Yes
Travel doc page	/docs/Travel/...	/en/docs/Travel/...	Yes
About page	/about	/en/about	Yes
Blog list page	/blog	/en/blog	No
Other doc page	Any doc outside /docs/Travel/...	Any doc outside /en/docs/Travel/...	No
Other custom page	Any custom page outside /about	Any custom page outside /en/about	No

Chinese and English versions of the same page share the same Discussion. The English path prefix /en is removed before the value is used as the giscus term:

/blog/2026/05/02/hamasushi-big-conveyor-belt-sushi-meal
/en/blog/2026/05/02/hamasushi-big-conveyor-belt-sushi-meal
  -> /blog/2026/05/02/hamasushi-big-conveyor-belt-sushi-meal

/docs/Travel/hong-kong-travel
/en/docs/Travel/hong-kong-travel
  -> /docs/Travel/hong-kong-travel

/about
/en/about
  -> /about

This keeps comments for a translated pair in one place instead of splitting the same article into two discussions.

GitHub Setup

Comments are stored in:

NeverGpDzy/docs-comments

The repository must satisfy these requirements:

1. The repository is public.
2. Discussions are enabled under Settings -> General -> Features.
3. The Announcements discussion category exists.
4. The giscus GitHub App is installed and authorized for NeverGpDzy/docs-comments.
5. There is no giscus.json, so origin domains are not restricted.

The frontend currently uses this giscus configuration:

Option	Value
repo	NeverGpDzy/docs-comments
repoId	R_kgDOSTPzRQ
category	Announcements
categoryId	DIC_kwDOSTPzRc4C8Qej
mapping	specific
strict	1
reactionsEnabled	1
emitMetadata	0
inputPosition	bottom
loading	lazy

repoId and categoryId are not secrets. They come from the script snippet generated by the giscus configuration page.

Code Structure

Key files:

File	Purpose
src/components/GiscusComments/index.js	Main comments component; owns giscus config, language, theme, and term generation
src/components/GiscusComments/styles.module.css	Comment section title, spacing, and divider styles
src/theme/BlogPostPage/index.js	Blog post swizzle layout; mounts comments automatically
src/theme/DocItem/Layout/index.js	Doc page swizzle layout; mounts comments only in the Travel branch
src/theme/MDXPage/index.js	Content-pages layout; mounts comments only on the About page
package.json	Declares the @giscus/react dependency

Component flow:

BlogPostPage
  -> BlogAudioPlayer
  -> BlogPostItem
  -> GiscusComments
  -> BlogPostPaginator

DocItem/Layout
  -> if isTravelDocMetadata(metadata)
       -> DocItemContent
       -> GiscusComments
       -> DocItemPaginator
  -> else
       -> normal doc layout without comments

MDXPage
  -> MDXContent
  -> if getGiscusTerm(metadata.permalink) === '/about'
       -> GiscusComments
  -> else
       -> normal MDX page without comments

Component Implementation

GiscusComments accepts an optional permalink:

<GiscusComments permalink={metadata.permalink} />

Both blog and doc layouts pass Docusaurus metadata permalink into the component instead of relying only on the browser location. This gives the component a stable path source during SSR, static generation, and client-side navigation.

The component handles four jobs.

1. Stable giscus term generation

getGiscusTerm() normalizes the path:

1. Remove #hash.
2. Remove ?query.
3. Remove the trailing /.
4. Remove the leading /en when present.
5. Fall back to / for an empty path.

Examples:

getGiscusTerm('/en/docs/Travel/hong-kong-travel/')
// => '/docs/Travel/hong-kong-travel'

getGiscusTerm('/blog/post-a?preview=1#comments')
// => '/blog/post-a'

Because giscus uses mapping="specific", term is the binding key between a page and its Discussion. If this value changes, old comments are not deleted, but the page will point to a different Discussion and can look like the comments were reset. Do not change the term rule casually.

2. Language synchronization

The component reads the current locale with useDocusaurusContext():

Current locale	giscus lang	Section title
zh-Hans	zh-CN	评论
en	en	Comments

3. Theme synchronization

The component reads the current Docusaurus color mode with useColorMode():

Docusaurus theme	giscus theme
light	light
dark	dark

When the site theme changes, React re-renders the component and updates the giscus theme.

4. Layout-level mounting only

The component is not written into article content files. It is mounted by theme layouts:

// src/theme/BlogPostPage/index.js
<BlogPostItem>{children}</BlogPostItem>
<GiscusComments permalink={metadata.permalink} />

// src/theme/DocItem/Layout/index.js
<DocItemContent>{children}</DocItemContent>
<GiscusComments permalink={metadata.permalink} />

// src/theme/MDXPage/index.js
{isAboutPage && <GiscusComments permalink={metadata.permalink} />}

BlogPostPage is only used by blog post pages, so the blog list page does not receive comments. DocItem/Layout renders comments only in the isTravel branch, so docs outside Travel do not receive comments. The content-pages layout renders comments only when getGiscusTerm(metadata.permalink) === '/about', so custom Markdown / MDX pages outside About do not receive comments.

Rules for New Content

New Blog Posts

Any new Chinese blog post under blog/ receives comments automatically.

If there is an English version, place it at:

i18n/en/docusaurus-plugin-content-blog/{same-file-name}

Keep the filename and slug aligned so the Chinese and English pages share the same Discussion.

New Travel Docs

Place the Chinese file at:

docs/Travel/{slug}.mdx

Place the English file at:

i18n/en/docusaurus-plugin-content-docs/current/Travel/{slug}.mdx

Keep the filename and slug aligned so the Chinese and English pages share the same Discussion.

Other Docs

Other docs do not show comments by default. If comments should be enabled for another doc category later, extend the category detection logic or add a clear branch in DocItem/Layout. Do not add the component manually inside each document.

New Custom Pages

Custom Markdown / MDX pages do not show comments by default. Currently only the About page enables comments through the path check in src/theme/MDXPage/index.js. If another custom page should receive comments later, add a clear path check in MDXPage. Do not insert the component manually inside the page content file.

Maintenance Notes

Do not change the term rule casually

term is the page-to-Discussion key. These changes would split old and new comments:

• Keeping /en instead of removing it.
• Switching from pathname to title.
• Keeping trailing slashes instead of removing them.
• Changing an article slug or permalink.

If a slug must change, the old Discussion remains in docs-comments, but the new page will create or use a different Discussion. Migration, merging, or linking must be handled manually in GitHub Discussions.

Do not put the component inside MDX

The current design is layout-level automatic mounting. The About page also receives comments through the MDXPage layout, not through an import in the About content file. Manual MDX usage can create duplicate comment sections, inconsistent bilingual behavior, and extra maintenance work.

Impact of not restricting origins

There is currently no giscus.json, so another site can theoretically embed the same giscus configuration. Comments still require GitHub login, and content can be deleted, locked, or managed in NeverGpDzy/docs-comments.

If origin restrictions are needed later, add giscus.json in the comments repository and update this document at the same time.

repoId and categoryId changes

If the comments repository is recreated, migrated, or moved to a different Discussion category, regenerate repoId and categoryId from the giscus configuration page and update src/components/GiscusComments/index.js.

Test Checklist

After changing the comments component or mount logic, run:

npm run build
npm run build:en

Check these pages:

Page	Expected result
/blog/2026/05/02/hamasushi-big-conveyor-belt-sushi-meal	Shows comments
/en/blog/2026/05/02/hamasushi-big-conveyor-belt-sushi-meal	Shows the same comments
/docs/Travel/hong-kong-travel	Shows comments
/en/docs/Travel/hong-kong-travel	Shows the same comments
/about	Shows comments
/en/about	Shows the same comments
/blog	No comments
/en/blog	No comments
Any non-Travel doc page	No comments
Any non-About custom page	No comments

After deployment, run a real comment test:

1. Post a test comment on a Chinese blog page.
2. Open the matching English blog page and confirm the same comment is visible.
3. Post a test comment on a Chinese Travel page.
4. Open the matching English Travel page and confirm the same comment is visible.
5. Post a test comment on /about.
6. Open /en/about and confirm the same comment is visible.
7. Confirm the Discussion was created under Announcements in NeverGpDzy/docs-comments.

Troubleshooting

The section title appears, but giscus does not load

Possible causes:

• The giscus App is not authorized for NeverGpDzy/docs-comments.
• The comments repository is not public.
• Discussions are not enabled.
• repoId or categoryId is wrong.
• The browser cannot reach GitHub or giscus.

Chinese and English pages do not share comments

Check:

• The Chinese and English pages use matching slugs.
• The English path uses the standard /en/... prefix.
• getGiscusTerm() still removes /en.
• No article manually changed its slug front matter.

Comments appear on non-Travel doc pages

Check src/theme/DocItem/Layout/index.js and confirm <GiscusComments /> is rendered only inside the isTravel branch.

Comments appear on the blog list page

Check whether a BlogPostItem/Footer wrapper or another list-level wrapper was added. The current implementation should only modify BlogPostPage.

The About page does not show comments

Check src/theme/MDXPage/index.js and confirm isAboutPage still uses getGiscusTerm(metadata.permalink) === '/about' and renders <GiscusComments permalink={metadata.permalink} />.

Design Tradeoffs

Reasons for choosing giscus:

• It works well for static sites and needs no backend.
• Comments live in GitHub Discussions, so the data is visible and manageable.
• Readers of a technical blog or knowledge base often already have GitHub accounts.
• React integration with Docusaurus layout code is straightforward.

Main limitations:

• Visitors need a GitHub account to comment.
• Comments depend on GitHub and giscus availability.
• Without origin restrictions, embedding is more open.

The current implementation prioritizes simple maintenance, bilingual consistency, and tight control over where comments appear.