Add advanced usage guide

ADVANCED-USAGE.md

@@ -0,0 +1,58 @@
+# advanced usage
+
+This guide highlights advanced usage of giscus through additional
+configurations.
+
+## `giscus.json`
+
+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][giscus.json]. The `giscus.json` file supports the
+following keys:
+
+- [`origins`](#origins)
+- [`originsRegex`](#originsregex)
+
+### `origins`
+
+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.
+
+```js
+string === window.origin
+```
+
+You can combine `origins` with [`originsRegex`](#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`:
+
+```json
+{
+  "origins": ["https://giscus.app"]
+}
+```
+
+### `originsRegex`
+
+Like [`origins`](#origins), but it accepts a list of regular expression
+patterns to test the origin. The test is done using the following code.
+
+```js
+new RegExp(pattern).test(window.origin)
+```
+
+Example `giscus.json`:
+
+```json
+{
+  "origins": ["https://giscus.app"],
+  "originsRegex": ["http://localhost:[0-9]+"]
+}
+```
+
+[giscus.json]: giscus.json

README.md

@@ -31,6 +31,10 @@ To comment, visitors must authorize the [giscus app][giscus-app] to [post on the
 
 If you're using giscus, consider [starring 🌟 giscus on GitHub][repo] and adding the [`giscus`][giscus-topic] topic [to your repository][topic-howto]! 🎉
 
+## advanced usage
+
+You can add additional configurations (e.g. allowing specific origins) by following the [advanced usage guide][advanced-usage].
+
 ## migrating
 
 If you've previously used other systems that utilize GitHub Issues (e.g. [utterances][utterances], [gitalk][gitalk]), you can [convert the existing issues into discussions][convert]. After the conversion, just make sure that the mapping between the discussion titles and the pages are correct, then giscus will automatically use the discussions.
@@ -49,6 +53,7 @@ See [CONTRIBUTING.md][contributing]
 [repo]: https://github.com/laymonage/giscus
 [giscus-topic]: https://github.com/topics/giscus
 [topic-howto]: https://docs.github.com/en/github/administering-a-repository/classifying-your-repository-with-topics
+[advanced-usage]: https://github.com/laymonage/giscus/blob/main/ADVANCED-USAGE.md
 [utterances]: https://github.com/utterance/utterances
 [gitalk]: https://github.com/gitalk/gitalk
 [convert]: https://docs.github.com/en/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion