This guide highlights advanced usage of giscus through additional configurations.
Additional configurations can be made by creating a giscus.json file at
the root of your repository. You can see an example
on this repository. The giscus.json file supports the
following keys:
You can restrict the domains that can load giscus with your repository's
discussions using the origins key. The origins key accepts a list of
strings that will be checked against the window.origin of the page that loads
giscus. The strings are compared using the following code.
string === window.originYou can combine origins with originsRegex. If none of the
strings in origins and originsRegex match window.origin, then giscus will
refuse to load. If origins and originsRegex are both empty lists (or
undefined), giscus will proceed to load the discussion.
Example giscus.json:
{
"origins": ["https://giscus.app"]
}Like origins, but it accepts a list of regular expression
patterns to test the origin. The test is done using the following code.
new RegExp(pattern).test(window.origin)Example giscus.json:
{
"origins": ["https://giscus.app"],
"originsRegex": ["http://localhost:[0-9]+"]
}You can set the default comment order, i.e. "oldest" (oldest to newest) or
"newest" (newest to oldest). This option defaults to "oldest".
Example giscus.json:
{
"defaultCommentOrder": "newest"
}Some of the data- attributes of the <script> tag may be used to further
customize giscus.
Instead of the built-in themes, you can supply a URL to a CSS file as the value
for the data-theme attribute. The URL will be used by giscus to construct a
<link rel="stylesheet"> element as the last child of the <head> element.
For example, given the following <script> tag:
<script src="https://giscus.app/client.js"
data-repo="giscus/giscus"
...
data-theme="https://giscus.app/themes/custom_example.css"
...>
</script>then giscus will add the following element:
<link id="giscus-theme" rel="stylesheet" crossorigin="anonymous" href="https://giscus.app/themes/custom_example.css">Please note that loading an external CSS file may be unsafe. Make sure that you trust the author and provider of the CSS file. We are not responsible if the CSS file that you use opens a security vulnerability to giscus users on your website. Make sure that your users are aware of this.
For more details, see creating new themes.
There are message events emitted by giscus to the parent window using
window.parent.postMessage(). You can listen to these events to update your
page based on giscus' state. For example:
function handleMessage(event: MessageEvent) {
if (event.origin !== 'https://giscus.app') return;
if (!(typeof event.data === 'object' && event.data.giscus)) return;
const giscusData = event.data.giscus;
// Do whatever you want with it, e.g. `console.log(giscusData)`.
// You'll need to make sure that `giscusData` contains the message you're
// expecting, e.g. by using `if ('discussion' in giscusData)`.
}
window.addEventListener('message', handleMessage);
// Some time later...
window.removeEventListener('message', handleMessage);The giscusData constant in the above example will dynamically contain the
message data as shown in the following interfaces. For more details of the
interfaces, see lib/types/giscus.ts and the interfaces imported
inside that module.
By default, giscus emits an error message to the parent whenever it encounters
an error. This is used by the client script to automatically delete invalid or
expired session data from the parent's localStorage. This isn't really useful
for most users, but you can receive the data if you need it. The message
interface is specified as the following:
interface IErrorMessage {
error: string;
}Following the handleMessage example above, that means giscusData will be of
type IErrorMessage:
if ('error' in giscusData) {
const errorMessage: IErrorMessage = giscusData;
console.error(errorMessage.error);
}If you enable the "Emit discussion metadata" feature by setting
data-emit-metadata="1" in the <script> tag, giscus will periodically emit
the discussion metadata using the following interface. Note that the data will
only be emitted if the discussion exists.
interface IMetadataMessage {
discussion: IDiscussionData;
viewer: IUser;
}Following the handleMessage example above, that means giscusData will be of
type IMetadataMessage:
if ('discussion' in giscusData) {
const metadataMessage: IMetadataMessage = giscusData;
console.log(metadataMessage.discussion);
console.log(metadataMessage.viewer);
}The contentWindow of giscus' <iframe> element also listens to message
events. You can send these events to update giscus based on your page's state.
For example:
function sendMessage<T>(message: T) {
const iframe = document.querySelector<HTMLIFrameElement>('iframe.giscus-frame');
if (!iframe) return;
iframe.contentWindow.postMessage({ giscus: message }, 'https://giscus.app');
}The T type of the message in the above example can be any of the following
interfaces. For more details of the interfaces, see
lib/types/giscus.ts and the interfaces imported inside that
module.
The ISetConfigMessage interface lets you change giscus' config on-the-fly
without having to reload the <script> or <iframe> elements. All of the
properties inside the setConfig property are optional, which means that
you can update a specific subset of the config and leave everything else as-is.
interface ISetConfigMessage {
setConfig: {
theme?: Theme;
repo?: string;
repoId?: string;
category?: string;
categoryId?: string;
term?: string;
description?: string;
number?: number;
reactionsEnabled?: boolean;
emitMetadata?: boolean;
inputPosition?: InputPosition;
lang?: AvailableLanguage;
};
}Following the sendMessage example above, in this case message will be of
type ISetConfigMessage:
sendMessage({
setConfig: {
theme: 'https://giscus.app/themes/custom_example.css',
reactionsEnabled: false,
}
});