MkDocs Material

Integrating Cactus Comments with the Material theme for MkDocs.

Please first complete the “Prerequisites” and “Register Your Site” sections in the quick start guide.

Add Custom Directory

If you do not have one already, you will need a custom_dir, set under theme in mkdocs.yml. This allows to extending or overriding parts of the theme.

  name: material
  custom_dir: overrides

Add main.html for overrides

In the custom_dir, create a file called main.html. This allows overriding a block, the comments block specifically in this case.

Override the content block

Set the contents of main.html to override the content block.

Make sure to change the siteName in the initComments section, and if needed, change the serverName and the defaultHomeserverUrl. See the quick start guide for more information.

{% block content %}
  {{ super() }}

<script type="text/javascript" src=""></script>
<link rel="stylesheet" href="" type="text/css">

<div id="comment-section">Loading Comments...</div>

try {
    var docCommentSectionId = document.getElementById('comments-section-id').innerHTML
} catch {
    var docCommentSectionId = "catch-all"
if (docCommentSectionId == null ){
    docCommentSectionId = "catch-all"

  node: document.getElementById("comment-section"),
  defaultHomeserverUrl: "",
  siteName: "<YOUR-SITE-NAME>",
  commentSectionId: docCommentSectionId,
  serverName: ""

{% endblock %}

Set page identifiers

In every markdown file for your site, put a hidden paragraph that contains an unique identifier for the comments section to use. Generally, these go at the top of the markdown file, but that is not required.

Note that a commentSectionId cannot include underscores.

<p hidden id="comments-section-id">put-unique-id-for-each-page-here</p>