vuepress-plugin-giscus-comment

Note: This plugin is provided for VuePress 2

Giscus plugin for VuePress 2.
This plugin register <GiscusComment/> custom element to your VuePress site.
You are free to use it on any theme or page.

Installation

yarn add -D vuepress-plugin-giscus-comment
# OR
npm install -D vuepress-plugin-giscus-comment

Usage

Method 1: Using the simple plugin configuration array

This method is simple and the most common.

module.exports = {
    plugins: [
        ['vuepress-plugin-giscus-comment',{/*options*/}]
    ]
};

When using with TypeScript, you can specify the type as shown below.

import {GiscusCommentPluginConfig} from 'vuepress-plugin-giscus-comment'

module.exports = {
    plugins: [
        ['vuepress-plugin-giscus-comment', {/*options*/}] as GiscusCommentPluginConfig
    ]
};

Method 2: Using the plugin configuration generator function

This method is a goes well with TypeScript.

import {GiscusCommentPlugin} from 'vuepress-plugin-giscus-comment';

module.exports = {
    plugins: [
        new GiscusCommentPlugin({/*options*/})
    ]
}

:card_file_box: Options

The plugin option has an interface as shown below.

interface GiscusCommentPluginOptions{
    /** @description The repository name */
    repo: `${string}/${string}`;

    /** @description The repository id */
    repoId: string;
    
    /** 
     * @description The discussion category name of repository
     * Required if 'mapping' value is not 'specific'
    */
    category?: string;

    /** 
     * @description The discussion category id of repository
     * Required if 'mapping' value is not 'specific'
    */
    categoryId?: string;

    /**
     * @description The mapping method between the embedding page and the embedded discussion
     * @default 'pathname'
     */
    mapping?: 'url' | 'title' | 'og:title' | 'pathname' | 'specific' | 'number';
    
    /**
     * @description Not required by Common mapping method
     * Required when 'mapping' value is 'specific' or 'number'
     */
    term?: string|number;
    
     /**
     * @description Whether to enable reactions for main post
     * @default true
     */
    reactionsEnabled?: boolean;

    /**
     * @description Whether to enable emit discussion metadata
     * @default false
     */
    emitMetadata?: boolean;

    /**
     * @description The theme name or custom theme css path that apply to giscus
     * @default 'light'
     */
    theme?:
        'light' | 'light_high_contrast' | 'light_protanopia' |
        'dark' | 'dark_high_contrast' | 'dark_protanopia' | 'dark_dimmed' |
        'transparent_dark' | 'preferred_color_scheme' |
        `/${string}` | `https://${string}`;

    /**
     * @description The location of comment box
     * @default 'bottom'
     */
    inputPosition?: 'top' | 'bottom';

    /**
     * @description The language name that apply to giscus
     * @default 'en'
     */
    lang?:
        'de' | 'en' | 'es' | 'fr' | 'gsw' | 'id' | 'it' | 'ja' |
        'ko' | 'pl' | 'ro' | 'ru' | 'tr' | 'vi' | 'zh-CN' | 'zh-TW';

    /**
     * @description Whether to load the comments lazily
     * @default true
     */
    lazyLoading?: boolean;
}

Example:

import {GiscusCommentPlugin} from 'vuepress-plugin-giscus-comment';

module.exports = {
    plugins: [
        new GiscusCommentPlugin({
               repo: '[ENTER REPOSITORY NAME HERE]',
               repoId: '[ENTER REPOSITORY ID HERE]',
               category: '[ENTER CATEGORY NAME HERE]',
               categoryId: '[ENTER CATEGORY ID HERE]',
               mapping: 'url',
               reactionsEnabled: false,
               emitMetadata: true,
               theme: 'dark',
               inputPosition: 'top',
               lang: 'en',
               lazyLoading: false
           })
    ]
}

:bulb: How to get my repo and category ids?

You can easily get it from Giscus Main page.