Integrating Giscus Comment System in VitePress

Giscus is a comment system based on GitHub Discussions. This article will provide a detailed guide on how to integrate Giscus into VitePress using the vitepress-plugin-comment-with-giscus plugin, including a special solution for private repositories and the installation process of the Giscus GitHub App.

Giscus Official Website

Before starting, please visit the official Giscus website: https://giscus.app

This website provides detailed instructions, configuration options, and is the place to obtain necessary configuration information for Giscus.

Solution for Private Repositories

If your VitePress project repository is private, you can create a separate public repository specifically for the Giscus comment system. This approach has several advantages:

1. Protect main project code: Your VitePress project code can remain private.
2. Separate comment management: Managing comments separately from the main project can be more convenient.
3. Maintain all Giscus features: By using a public repository, you can fully utilize all features of Giscus.

Steps

1. Create a new public repository:

   • Create a new public repository on GitHub specifically for storing comments.
   • You can give it a relevant name, such as "my-site-comments".

2. Enable Discussions in the new repository:

   • Go to the repository settings.
   • Enable "Discussions" in the "Features" section.

3. Install the Giscus GitHub App: This step is crucial. Here's a detailed guide:

   a. Visit the Giscus GitHub App installation page: https://github.com/apps/giscus

   This is the direct link to install the Giscus GitHub App. Clicking it will take you directly to the installation page.

   b. On the installation page, click the green "Install" button.

   c. Choose the installation location:

   • If you have multiple organization accounts, GitHub will ask where you want to install Giscus.
   • Select your personal account or the organization that contains your newly created public repository.

   d. Configure repository access:

   • On the next page, you can choose to install Giscus on all repositories or only select specific ones.
   • For security reasons, it's recommended to choose "Only select repositories".
   • Then select your newly created public repository for comments from the list.

   e. Confirm installation:

   • Carefully check if your selection is correct.
   • Click the "Install" button to confirm the installation.

   f. Authorize access:

   • GitHub may ask you to enter your password again to confirm this operation.

   g. Complete installation:

   • After installation, you will be redirected to the Giscus configuration page or your GitHub settings page.

   Once installed, Giscus will have permission to access the Discussions in your specified repository. This allows Giscus to create, read, and manage Discussions, which is necessary for the comment system to function properly.

4. Configure Giscus:

   • Visit the Giscus configuration page.
   • Use the information from your newly created public repository for configuration.
   • Select other required settings (such as language, theme, etc.).

Integrating Giscus in VitePress

Using the vitepress-plugin-comment-with-giscus plugin can simplify the integration process.

Installing the Plugin

Install the vitepress-plugin-comment-with-giscus plugin:

# Using npm
npm i vitepress-plugin-comment-with-giscus

# Or using yarn
yarn add vitepress-plugin-comment-with-giscus

Configuring the Plugin

Add the following configuration to the index.js file in the .vitepress/theme directory:

import DefaultTheme from 'vitepress/theme';
import giscusTalk from 'vitepress-plugin-comment-with-giscus';
import { useData, useRoute } from 'vitepress';
import { toRefs } from "vue";

export default {
...DefaultTheme,
enhanceApp(ctx) {
DefaultTheme.enhanceApp(ctx);
},
setup() {
const { frontmatter } = toRefs(useData());
const route = useRoute();

        giscusTalk({
            repo: 'your-username/your-repo-name',
            repoId: 'your-repo-id',
            category: 'Announcements', // or other category
            categoryId: 'your-category-id',
            mapping: 'pathname',
            inputPosition: 'top',
            lang: 'en',
            lightTheme: 'light',
            darkTheme: 'transparent_dark',
        }, {
            frontmatter,
            route
        }, true);
    }
};

Obtaining Giscus Configuration

To obtain the necessary configuration information, follow these steps:

Visit the Giscus configuration page

Fill in your repository information (using the public comment repository information) and select preferred settings Find the corresponding configuration values in the generated script

Customization Options

homePageShowComment: Set whether to display the comment area on the homepage (default is false) locales: Configure multi-language support Use comment: false in the frontmatter to disable comments on specific pages