Giscus

Giscus v1.2.3

This is a Hugo theme component to add the Giscus comment system to static websites.

Giscus is a comments system powered by GitHub Discussions.

Note: Giscus is still under active development. GitHub is also still actively developing Discussions and its API. Thus, some features of Giscus may break or change over time. We will keep an eye out for any updates and implement them here in time.

Configuration

The module accepts configuration via params section in your configuration file.

 1[dnb]
 2  [dnb.giscus]
 3    dataCategory = 'Comments'
 4    dataCategoryId = 'ABCDEFGHIJKLMNOPQRST'
 5    dataEmitMetadata = '0'
 6    dataInputPosition = 'top'
 7    dataLang = 'en'
 8    dataLoading = 'lazy'
 9    dataMapping = 'specific'
10    dataReactionsEnabled = '1'
11    dataRepo = 'username/reponame'
12    dataRepoId = 'ABCDEFGHIJKLMNOPQSTUVXYZABCDEFGH'
13    dataTheme = 'dark'
14    dataThemeType = 'default'
15    src = 'https://giscus.app/client.js'
 1dnb:
 2  giscus:
 3    dataCategory: Comments
 4    dataCategoryId: ABCDEFGHIJKLMNOPQRST
 5    dataEmitMetadata: "0"
 6    dataInputPosition: top
 7    dataLang: en
 8    dataLoading: lazy
 9    dataMapping: specific
10    dataReactionsEnabled: "1"
11    dataRepo: username/reponame
12    dataRepoId: ABCDEFGHIJKLMNOPQSTUVXYZABCDEFGH
13    dataTheme: dark
14    dataThemeType: default
15    src: https://giscus.app/client.js
 1{
 2   "dnb": {
 3      "giscus": {
 4         "dataCategory": "Comments",
 5         "dataCategoryId": "ABCDEFGHIJKLMNOPQRST",
 6         "dataEmitMetadata": "0",
 7         "dataInputPosition": "top",
 8         "dataLang": "en",
 9         "dataLoading": "lazy",
10         "dataMapping": "specific",
11         "dataReactionsEnabled": "1",
12         "dataRepo": "username/reponame",
13         "dataRepoId": "ABCDEFGHIJKLMNOPQSTUVXYZABCDEFGH",
14         "dataTheme": "dark",
15         "dataThemeType": "default",
16         "src": "https://giscus.app/client.js"
17      }
18   }
19}

The data-parameter correspond with the parameters of Giscus. The four parameters dataRepo, dataRepoId, dataCategory, and dataCategoryId are required. All other parameters are optional and have default values as shown in the sample above.

You can find the proper values for your setup by filling out the form on the Giscus page.

The default dataMapping is set to specific and will use the title of the post as term.

Advanced setup

With a little bit of more work you can set Giscus up to allow only connections from specific sources and define the comment order.

This can be done with this module’s configuration and future updates to these features will be integrated. Or you create the giscus.json in your static directory manually and keep it up to date. The instructions are here.

To configure the module to create the giscus.json add the custom output format GISCUS to your home section:

1[outputs]
2  home = ['HTML', 'GISCUS']
1outputs:
2  home:
3  - HTML
4  - GISCUS
1{
2   "outputs": {
3      "home": [
4         "HTML",
5         "GISCUS"
6      ]
7   }
8}

Be careful to not override the existing home output formats.

Once added you will find a giscus.json in your website root.

Comment sort order:

Available options are oldest (sorting from oldest to newest comment) and newest (sorting newest to oldest).

1[dnb]
2  [dnb.giscus]
3    [dnb.giscus.extended]
4      defaultCommentOrder = 'oldest'
1dnb:
2  giscus:
3    extended:
4      defaultCommentOrder: oldest
1{
2   "dnb": {
3      "giscus": {
4         "extended": {
5            "defaultCommentOrder": "oldest"
6         }
7      }
8   }
9}

Origin setup:

1[dnb]
2  [dnb.giscus]
3    [dnb.giscus.extended]
4      origins = ['https://yourdomainname.ext', 'http://localhost:1313']
5      originsRegex = ['http://localhost:(1313|8080)']
1dnb:
2  giscus:
3    extended:
4      origins:
5      - https://yourdomainname.ext
6      - http://localhost:1313
7      originsRegex:
8      - http://localhost:(1313|8080)
 1{
 2   "dnb": {
 3      "giscus": {
 4         "extended": {
 5            "origins": [
 6               "https://yourdomainname.ext",
 7               "http://localhost:1313"
 8            ],
 9            "originsRegex": [
10               "http://localhost:(1313|8080)"
11            ]
12         }
13      }
14   }
15}

Add your origins to the params configuration. Leave the options out to not add them to your giscus.json.

Setup your own theme

Using dataThemeType set to local you can add a relative path as theme. This will be translated to the absolute URL depending on development or production environment. If your theme is finished you can remove dataThemeType and just add the full URL to your theme to the dataTheme variable.