OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Added guide for setting up Giscus

Browse Source
This commit is contained in:
squidfunk 2022-01-16 12:11:24 +01:00
parent 29cc1dddfa
commit f9e9418462
3 changed files with 75 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -106,7 +106,7 @@
* **Many configuration options** — change the color palette, font families, * **Many configuration options** — change the color palette, font families,
language, icons, favicon and logo. Add a source repository link, links to your 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 * **Truly international** — thanks to many contributors, Material for MkDocs
includes translations for more than 40 languages and offers full native RTL includes translations for more than 40 languages and offers full native RTL

1
docs/customization.md
View File

@ -178,7 +178,6 @@ The following template blocks are provided by the theme:
| `announce` | Wraps the announcement bar | | `announce` | Wraps the announcement bar |
| `config` | Wraps the JavaScript application config | | `config` | Wraps the JavaScript application config |
| `content` | Wraps the main content | | `content` | Wraps the main content |
| `disqus` | Wraps the Disqus integration |
| `extrahead` | Empty block to add custom meta tags | | `extrahead` | Empty block to add custom meta tags |
| `fonts` | Wraps the font definitions | | `fonts` | Wraps the font definitions |
| `footer` | Wraps the footer with navigation and copyright | | `footer` | Wraps the footer with navigation and copyright |

158
docs/setup/adding-a-comment-system.md
View File

@ -5,104 +5,92 @@ template: overrides/main.html
# Adding a comment system # Adding a comment system
Material for MkDocs allows to easily add the third-party comment system of your 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, choice to the footer of any page by using [theme extension]. As an example,
we'll be integrating [Disqus] a wildly popular comment provider, but others we'll be integrating [Giscus], which is Open Source, free, and uses GitHub
can be integrate with the same principles discussions as a backend.
[Disqus]: https://disqus.com/ [Giscus]: https://giscus.app/
## Customization ## Customization
### Disqus integration ### Giscus integration
In order to integrate a third-party comment provider offering a JavaScript-based Before you can use [Giscus], you need to complete the following steps:
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:
=== ":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 ``` html
<!-- Add copied contents from original content.html here --> <script
src="https://giscus.app/client.js"
<!-- Get setting from mkdocs.yml, but allow page-level overrides --> data-repo="<username>/<repository>"
{% set disqus = config.extra.disqus %} data-repo-id="..."
{% if page and page.meta and page.meta.disqus is string %} data-category="..."
{% set disqus = page.meta.disqus %} data-category-id="..."
{% endif %} data-mapping="pathname"
data-reactions-enabled="1"
<!-- Inject Disqus into current page --> data-emit-metadata="1"
{% if not page.is_homepage and disqus %} data-theme="light"
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2> data-lang="en"
<div id="disqus_thread"></div> crossorigin="anonymous"
<script> async
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> </script>
{% endif %}
``` ```
1. Ensure you've set [`site_url`][site_url] in `mkdocs.yml`. 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.
=== ":octicons-file-code-16: mkdocs.yml" 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:
``` yaml ``` html hl_lines="6"
extra: {% block content %}
disqus: <shortname> # (1)! {{ super() }}
```
1. Add your Disqus [shortname] here. <!-- 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 [theme extension]: ../customization.md#extending-the-theme
[content partial]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/content.html [overriding blocks]: ../customization.md#overriding-blocks
[shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname [setting the page template]: ../reference/index.md#setting-the-page-template
#### 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