Skip to content

Commit f9e9418

Browse files
squidfunksquidfunk
committed
Added guide for setting up Giscus
1 parent 29cc1dd commit f9e9418

File tree

3 files changed

+79
-92
lines changed

3 files changed

+79
-92
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@
106106

107107
* **Many configuration options** — change the color palette, font families,
108108
language, icons, favicon and logo. Add a source repository link, links to your
109-
social profiles, Google Analytics and Disqus - all with a few lines of config.
109+
social profiles, and Google Analytics - all with a few lines of config.
110110

111111
* **Truly international** — thanks to many contributors, Material for MkDocs
112112
includes translations for more than 40 languages and offers full native RTL

‎docs/customization.md

-1
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,6 @@ The following template blocks are provided by the theme:
178178
| `announce` | Wraps the announcement bar |
179179
| `config` | Wraps the JavaScript application config |
180180
| `content` | Wraps the main content |
181-
| `disqus` | Wraps the Disqus integration |
182181
| `extrahead` | Empty block to add custom meta tags |
183182
| `fonts` | Wraps the font definitions |
184183
| `footer` | Wraps the footer with navigation and copyright |

‎docs/setup/adding-a-comment-system.md

+78-90
Original file line numberDiff line numberDiff line change
@@ -5,104 +5,92 @@ template: overrides/main.html
55
# Adding a comment system
66

77
Material for MkDocs allows to easily add the third-party comment system of your
8-
choice to the footer of every page by using [theme extension]. As an example,
9-
we'll be integrating [Disqus] a wildly popular comment provider, but others
10-
can be integrate with the same principles
8+
choice to the footer of any page by using [theme extension]. As an example,
9+
we'll be integrating [Giscus], which is Open Source, free, and uses GitHub
10+
discussions as a backend.
1111

12-
[Disqus]: https://disqus.com/
12+
[Giscus]: https://giscus.app/
1313

1414
## Customization
1515

16-
### Disqus integration
16+
### Giscus integration
1717

18-
In order to integrate a third-party comment provider offering a JavaScript-based
19-
solution, follow the guide on [theme extension], copy the contents from the
20-
[`content.html`][content partial] partial and create a file at the same location
21-
in the `overrides` folder:
18+
Before you can use [Giscus], you need to complete the following steps:
2219

23-
=== ":octicons-file-code-16: overrides/partials/content.html"
20+
1. __Install the [Giscus GitHub App]__ and grant access to the repository
21+
that should host comments as GitHub discussions. Note that this can be a
22+
repository different from your documentation.
23+
2. __Visit [Giscus] and generate the snippet__ through their configuration tool
24+
to load the comment system. Copy the snippet for the next step. The
25+
resulting snippet should look similar to this:
2426

2527
``` html
26-
<!-- Add copied contents from original content.html here -->
27-
28-
<!-- Get setting from mkdocs.yml, but allow page-level overrides -->
29-
{% set disqus = config.extra.disqus %}
30-
{% if page and page.meta and page.meta.disqus is string %}
31-
{% set disqus = page.meta.disqus %}
32-
{% endif %}
33-
34-
<!-- Inject Disqus into current page -->
35-
{% if not page.is_homepage and disqus %}
36-
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
37-
<div id="disqus_thread"></div>
38-
<script>
39-
var disqus_config = function() {
40-
this.page.url = "{{ page.canonical_url }}"
41-
this.page.identifier =
42-
"{{ page.canonical_url | replace(config.site_url, '') }}" // (1)!
43-
}
44-
45-
/* Set up for the first time */
46-
if (typeof DISQUS === "undefined") {
47-
var script = document.createElement("script")
48-
script.async = true
49-
script.src = "https://{{ disqus }}.disqus.com/embed.js"
50-
script.setAttribute("data-timestamp", Date.now())
51-
52-
/* Inject script tag */
53-
document.body.appendChild(script)
54-
55-
/* Set up on navigation (instant loading) */
56-
} else {
57-
DISQUS.reset({
58-
reload: true,
59-
config: disqus_config
60-
})
61-
}
62-
</script>
63-
{% endif %}
28+
<script
29+
src="https://giscus.app/client.js"
30+
data-repo="<username>/<repository>"
31+
data-repo-id="..."
32+
data-category="..."
33+
data-category-id="..."
34+
data-mapping="pathname"
35+
data-reactions-enabled="1"
36+
data-emit-metadata="1"
37+
data-theme="light"
38+
data-lang="en"
39+
crossorigin="anonymous"
40+
async
41+
>
42+
</script>
6443
```
6544

66-
1. Ensure you've set [`site_url`][site_url] in `mkdocs.yml`.
67-
68-
=== ":octicons-file-code-16: mkdocs.yml"
69-
70-
``` yaml
71-
extra:
72-
disqus: <shortname> # (1)!
73-
```
74-
75-
1. Add your Disqus [shortname] here.
76-
45+
You can either integrate [Giscus] on every page by overriding the `main.html`
46+
template, or create a new template (e.g. `blog.html`) to extend from `main.html`
47+
which includes the comment system, so you can decide for each page whether you
48+
want to allow comments or not.
49+
50+
In order to integrate [Giscus], follow the guide on [theme extension] and
51+
[override the `content` block][overriding blocks], extending the default by
52+
calling the `super()` function at the beginning of the block:
53+
54+
``` html hl_lines="6"
55+
{% block content %}
56+
{{ super() }}
57+
58+
<!-- Giscus -->
59+
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
60+
<!-- Replace with generated snippet -->
61+
62+
<!-- Reload on palette change -->
63+
<script>
64+
var palette = __md_get("__palette")
65+
if (palette && typeof palette.color === "object")
66+
if (palette.color.scheme === "slate") {
67+
var giscus = document.querySelector("script[src*=giscus]")
68+
giscus.setAttribute("data-theme", "dark") // (1)!
69+
}
70+
71+
/* Register event handlers after documented loaded */
72+
document.addEventListener("DOMContentLoaded", function() {
73+
var ref = document.querySelector("[data-md-component=palette]")
74+
component$.subscribe(function (component) {
75+
if (component.ref === ref)
76+
location.reload()
77+
})
78+
})
79+
</script>
80+
{% endblock %}
81+
```
82+
83+
1. This code block ensures that [Giscus] renders with a dark theme when the
84+
palette is set to `slate`. Note that multiple dark themes are available,
85+
so you can change it to your liking.
86+
87+
Replace the highlighted line with the snippet you generated with the [Giscus]
88+
configuration tool in the previous step. If you extended `main.html`, you should
89+
now see the [Giscus] comment system at the bottom of each page. If you created
90+
a new, separate template, you can enable Giscus by [setting the page template]
91+
via front matter.
92+
93+
[Giscus GitHub App]: https://github.com/apps/giscus
7794
[theme extension]: ../customization.md#extending-the-theme
78-
[content partial]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/content.html
79-
[shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
80-
81-
#### on a single page
82-
83-
When [Metadata] is enabled, Disqus can be enabled or disabled for a single page
84-
with custom front matter. Add the following lines at the top of a Markdown file:
85-
86-
=== ":octicons-check-circle-fill-16: Enabled"
87-
88-
``` bash
89-
---
90-
disqus: <shortname>
91-
---
92-
93-
# Document title
94-
...
95-
```
96-
97-
=== ":octicons-skip-16: Disabled"
98-
99-
``` bash
100-
---
101-
disqus: ""
102-
---
103-
104-
# Document title
105-
...
106-
```
107-
108-
[Metadata]: extensions/python-markdown.md#metadata
95+
[overriding blocks]: ../customization.md#overriding-blocks
96+
[setting the page template]: ../reference/index.md#setting-the-page-template

0 commit comments

Comments
 (0)