Add comments to an MkDocs site

1. Load the script

In mkdocs.yml, point the theme at a folder for your overrides and add the script:

theme:
  name: material
  custom_dir: overrides

extra_javascript:
  - path: https://disfora.com/public/disfora.js
    async: true

The path and async form needs MkDocs 1.5 or later.

2. Fill the comments partial

Create this file. Material includes it at the end of every page:

{% if page.meta.comments %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  <div data-disfora-comments></div>
{% endif %}

3. Turn comments on

Add comments: true to the front matter of each page that should have comments:

---
comments: true
---

# Guide

With navigation.instant turned on, Material loads pages without a full reload. The script is loaded once, and Disfora loads the right thread whenever a page with comments appears.

Other MkDocs themes

With the built-in mkdocs or readthedocs theme, set custom_dir: overrides under theme as above, and extend the page template instead:

{% extends "base.html" %}

{% block content %}
  {{ super() }}
  <div data-disfora-comments></div>
{% endblock %}

That adds comments to every page. Keep the extra_javascript entry from step 1.

Check it on your site

Disfora only loads on the domain in your project, so mkdocs serve won't show it. Deploy, then verify your domain if you haven't yet, and open a page with comments enabled on your live site.

Ask a question

Something missing or unclear? Ask here and we'll answer in the thread.