Adding a comment system¶

Material for MkDocs is natively integrated with Disqus, a comment system that provides a wide range of features like social integrations, user profiles, as well as spam and moderation tools. Of course, other comment systems can be integrated, too.

Configuration¶

Disqus¶

Source · Default: none

First, ensure you've set site_url in mkdocs.yml. Then, to integrate Material for MkDocs with Disqus, create an account and a site giving you a shortname, and add it to mkdocs.yml:

extra:
  disqus: <shortname>

This will insert a comment system on every page, except the index page.

Metadata¶

The Metadata extension, which is part of the standard Markdown library, adds the ability to add front matter to a document and can be enabled via mkdocs.yml:

markdown_extensions:
  - meta

Front matter is written as a series of key-value pairs at the beginning of the Markdown document, delimited by a blank line which ends the YAML context.

Customization¶

Selective integration¶

Source · Difficulty: easy

If the Metadata extension is enabled, you can disable or enable Disqus for specific pages by adding the following to the front matter of a page:

---
disqus: <shortname>
---

...

---
disqus: ""
---

...

Other comment systems¶

Source · Difficulty: easy

In order to integrate another JavaScript-based comment system provider, you can extend the theme and override the disqus block:

{% block disqus %}
  <!-- Add custom comment system integration here -->
{% endblock %}