Skip to content

Commit

Permalink
Added guide for setting up Giscus
Browse files Browse the repository at this point in the history
  • Loading branch information
@squidfunk
squidfunk committed Jan 16, 2022
1 parent 29cc1dd commit f9e9418
Show file tree
Hide file tree
Showing 3 changed files with 79 additions and 92 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Expand Up @@ -106,7 +106,7 @@

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

* **Truly international** — thanks to many contributors, Material for MkDocs
includes translations for more than 40 languages and offers full native RTL
Expand Down
1 change: 0 additions & 1 deletion docs/customization.md
View file
Expand Up @@ -178,7 +178,6 @@ The following template blocks are provided by the theme:
| `announce` | Wraps the announcement bar |
| `config` | Wraps the JavaScript application config |
| `content` | Wraps the main content |
| `disqus` | Wraps the Disqus integration |
| `extrahead` | Empty block to add custom meta tags |
| `fonts` | Wraps the font definitions |
| `footer` | Wraps the footer with navigation and copyright |
Expand Down
168 changes: 78 additions & 90 deletions docs/setup/adding-a-comment-system.md
View file
Expand Up @@ -5,104 +5,92 @@ template: overrides/main.html
# Adding a comment system

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

[Disqus]: https://disqus.com/
[Giscus]: https://giscus.app/

## Customization

### Disqus integration
### Giscus integration

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

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

``` html
<!-- Add copied contents from original content.html here -->

<!-- Get setting from mkdocs.yml, but allow page-level overrides -->
{% set disqus = config.extra.disqus %}
{% if page and page.meta and page.meta.disqus is string %}
{% set disqus = page.meta.disqus %}
{% endif %}

<!-- Inject Disqus into current page -->
{% if not page.is_homepage and disqus %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<div id="disqus_thread"></div>
<script>
var disqus_config = function() {
this.page.url = "{{ page.canonical_url }}"
this.page.identifier =
"{{ page.canonical_url | replace(config.site_url, '') }}" // (1)!
}

/* Set up for the first time */
if (typeof DISQUS === "undefined") {
var script = document.createElement("script")
script.async = true
script.src = "https://{{ disqus }}.disqus.com/embed.js"
script.setAttribute("data-timestamp", Date.now())

/* Inject script tag */
document.body.appendChild(script)

/* Set up on navigation (instant loading) */
} else {
DISQUS.reset({
reload: true,
config: disqus_config
})
}
</script>
{% endif %}
<script
src="https://giscus.app/client.js"
data-repo="<username>/<repository>"
data-repo-id="..."
data-category="..."
data-category-id="..."
data-mapping="pathname"
data-reactions-enabled="1"
data-emit-metadata="1"
data-theme="light"
data-lang="en"
crossorigin="anonymous"
async
>
</script>
```

1. Ensure you've set [`site_url`][site_url] in `mkdocs.yml`.

=== ":octicons-file-code-16: mkdocs.yml"

``` yaml
extra:
disqus: <shortname> # (1)!
```

1. Add your Disqus [shortname] here.

You can either integrate [Giscus] on every page by overriding the `main.html`
template, or create a new template (e.g. `blog.html`) to extend from `main.html`
which includes the comment system, so you can decide for each page whether you
want to allow comments or not.

In order to integrate [Giscus], follow the guide on [theme extension] and
[override the `content` block][overriding blocks], extending the default by
calling the `super()` function at the beginning of the block:

``` html hl_lines="6"
{% block content %}
{{ super() }}

<!-- Giscus -->
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- Replace with generated snippet -->

<!-- Reload on palette change -->
<script>
var palette = __md_get("__palette")
if (palette && typeof palette.color === "object")
if (palette.color.scheme === "slate") {
var giscus = document.querySelector("script[src*=giscus]")
giscus.setAttribute("data-theme", "dark") // (1)!
}
/* Register event handlers after documented loaded */
document.addEventListener("DOMContentLoaded", function() {
var ref = document.querySelector("[data-md-component=palette]")
component$.subscribe(function (component) {
if (component.ref === ref)
location.reload()
})
})
</script>
{% endblock %}
```

1. This code block ensures that [Giscus] renders with a dark theme when the
palette is set to `slate`. Note that multiple dark themes are available,
so you can change it to your liking.

Replace the highlighted line with the snippet you generated with the [Giscus]
configuration tool in the previous step. If you extended `main.html`, you should
now see the [Giscus] comment system at the bottom of each page. If you created
a new, separate template, you can enable Giscus by [setting the page template]
via front matter.

[Giscus GitHub App]: https://github.com/apps/giscus
[theme extension]: ../customization.md#extending-the-theme
[content partial]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/content.html
[shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname

#### on a single page

When [Metadata] is enabled, Disqus can be enabled or disabled for a single page
with custom front matter. Add the following lines at the top of a Markdown file:

=== ":octicons-check-circle-fill-16: Enabled"

``` bash
---
disqus: <shortname>
---

# Document title
...
```

=== ":octicons-skip-16: Disabled"

``` bash
---
disqus: ""
---

# Document title
...
```

[Metadata]: extensions/python-markdown.md#metadata
[overriding blocks]: ../customization.md#overriding-blocks
[setting the page template]: ../reference/index.md#setting-the-page-template

1 comment on commit f9e9418

@Andre601
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's actually a good change. 👍

Please sign in to comment.