Integrate Mastodon as comment system into your posts

[Andre601]

Recently did I ask in the Material for MkDocs repository¹ about how I could implement a Mastodon-based comment system (#5728).
After looking a bit myself did I manage to setup a working version using some blog post on how to do it.

The post giving the code snippet and explaining it was made for Hugo, so some adjustments were required to make it work.
And since there is no post addressing this for MkDocs and the Material for MkDocs theme am I making this post now.

I already posted a Paste² with some basic instructions, but I feel like a more in-depth explanation was useful to have, so here we are.

Enjoy!

Prerequisites

To make this comment system work you need...

• A Mastodon account
• The Material for MkDocs theme
• Knowledge in how to extend the theme (Override files)

Limitations and issues

This setup compared to Giscuss has a few limitations.
The most annoying one is the requirement for the post to exist before your blog page...

We need a Post ID to load and displays replies from. So you either need to make a post, copy the id and add to your blog post, or make the blog post, create a Mastodon toot, copy id, edit blog post...

Another issue - at least with my aproach - is that it isn't directly compatible with Material for MkDocs' theme as in, it won't adapt itself to switching the theme.
I designed this for dark theme only, so the colours won't adjust themself.

Other Notes

During this post we will assume the following setups:

• The custom_dir setting of theme in your mkdocs.yml is set to theme
• The Mastodon instance is example.com and the user is Example

Step 1: Creating the files

If you haven't already, you need to extend the Material for MkDocs theme³ and create a new file in the theme extension folder.
The file we need is comments.html which is located in partials/ so the full path - relative to the mkdocs.yml file - would be theme/partials/comments.html

In addition should you make a CSS file in the assets directory (i.e. docs/assets/stylesheets/comments.css) and add it as an entry to the extra_css setting of your mkdocs.yml to get it loaded as CSS for your pages.

Now open the files in a text editor of your choice...

Step 2: Adding content

You need to add some content to the comments.html file and the comments.css file.

comments.html

{% if page.meta.comments %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  {% if page.meta.comment_id %}
    <noscript>
      <div class="admonition danger">
        <p class="admonition-title">
          Please enable Javascript to see comments from Mastodon.
        </p>
      </div>
    </noscript>
    <p>
      <a href="https://{{ config.extra.mastodon.host }}/@{{ config.extra.mastodon.user }}/{{ page.meta.comment_id }}">Comment on this blog post</a> using a Fediverse-compatible Account (Mastodon or alike).
    </p>
    
    <p id="mastodon-comments-list"></p>
    
    <script src="https://cdnjs.cloudflare.com/ajax/libs/dompurify/2.4.1/purify.min.js" integrity="sha512-uHOKtSfJWScGmyyFr2O2+efpDx2nhwHU2v7MVeptzZoiC7bdF6Ny/CmZhN2AwIK1oCFiVQQ5DA/L9FSzyPNu6Q=="    crossorigin="anonymous" referrerpolicy="no-referrer"></script>
    <script type="text/javascript">
      var host = '{{ config.extra.mastodon.host }}';
      var user = '{{ config.extra.mastodon.user }}';
      var id = '{{ page.meta.comment_id }}'
    
      function escapeHtml(unsafe) {
        return unsafe
          .replace(/&/g, "&amp;")
          .replace(/</g, "&lt;")
          .replace(/>/g, "&gt;")
          .replace(/"/g, "&quot;")
          .replace(/'/g, "&#039;");
      }
    
      var commentsLoaded = false;
    
      function toot_active(toot, what) {
        var count = toot[what+'_count'];
        return count > 0 ? 'active' : '';
      }
    
      function toot_count(toot, what) {
        var count = toot[what+'_count'];
        return count > 0 ? count : '';
      }
    
      function user_account(account) {
        var result =`@${account.acct}`;
        if (account.acct.indexOf('@') === -1) {
          var domain = new URL(account.url)
          result += `@${domain.hostname}`
        }
        return result;
      }
    
      function render_toots(toots, in_reply_to, depth) {
        var tootsToRender = toots
          .filter(toot => toot.in_reply_to_id === in_reply_to)
          .sort((a, b) => a.created_at.localeCompare(b.created_at));
        tootsToRender.forEach(toot => render_toot(toots, toot, depth));
      }
    
      function render_toot(toots, toot, depth) {
        toot.account.display_name = escapeHtml(toot.account.display_name);
        toot.account.emojis.forEach(emoji => {
          toot.account.display_name = toot.account.display_name.replace(`:${emoji.shortcode}:`, `<img src="${escapeHtml(emoji.static_url)}" alt="Emoji ${emoji.shortcode}" height="20" width="20" />`);
        });
        mastodonComment =
          `<div class="mastodon-comment" style="margin-left: calc(var(--mastodon-comment-indent) * ${depth})">
            <div class="author">
              <div class="avatar">
                <img src="${escapeHtml(toot.account.avatar_static)}" height=60 width=60 alt="">
              </div>
              <div class="details">
                <a class="name" href="${toot.account.url}" rel="nofollow">${toot.account.display_name}</a>
                <a class="user" href="${toot.account.url}" rel="nofollow">${user_account(toot.account)}</a>
              </div>
              <a class="date" href="${toot.url}" rel="nofollow">${toot.created_at.substr(0, 10)} ${toot.created_at.substr(11, 8)}</a>
            </div>
            <div class="content">${toot.content}</div>
            <div class="attachments">
              ${toot.media_attachments.map(attachment => {
                if (attachment.type === 'image') {
                  return `<a href="${attachment.url}" rel="nofollow"><img src="${attachment.preview_url}" alt="${attachment.description}" /></a>`;
                } else if (attachment.type === 'video') {
                  return `<video controls><source src="${attachment.url}" type="${attachment.mime_type}"></video>`;
                } else if (attachment.type === 'gifv') {
                  return `<video autoplay loop muted playsinline><source src="${attachment.url}" type="${attachment.mime_type}"></video>`;
                } else if (attachment.type === 'audio') {
                  return `<audio controls><source src="${attachment.url}" type="${attachment.mime_type}"></audio>`;
                } else {
                  return `<a href="${attachment.url}" rel="nofollow">${attachment.type}</a>`;
                }
              }).join('')}
            </div>
            <div class="status">
              <div class="twemoji replies ${toot_active(toot, 'replies')}">
                <a href="${toot.url}" rel="nofollow">{% include ".icons/fontawesome/solid/reply.svg" %}${toot_count(toot, 'replies')}</a>
              </div>
              <div class="twemoji reblogs ${toot_active(toot, 'reblogs')}">
                <a href="${toot.url}" rel="nofollow">{% include ".icons/fontawesome/solid/retweet.svg" %}${toot_count(toot, 'reblogs')}</a>
              </div>
              <div class="twemoji favourites ${toot_active(toot, 'favourites')}">
                <a href="${toot.url}" rel="nofollow">{% include ".icons/fontawesome/solid/star.svg" %}${toot_count(toot, 'favourites')}</a>
              </div>
            </div>
          </div>`;
        document.getElementById('mastodon-comments-list').appendChild(DOMPurify.sanitize(mastodonComment, {'RETURN_DOM_FRAGMENT': true}));
    
        render_toots(toots, toot.id, depth + 1)
      }
    
      function loadComments() {
        if (commentsLoaded) return;
    
        document.getElementById("mastodon-comments-list").innerHTML = "Loading comments from the Fediverse...";
    
        fetch('https://' + host + '/api/v1/statuses/' + id + '/context')
          .then(function(response) {
            return response.json();
          })
          .then(function(data) {
            if(data['descendants'] && Array.isArray(data['descendants']) && data['descendants'].length > 0) {
                document.getElementById('mastodon-comments-list').innerHTML = "";
                render_toots(data['descendants'], id, 0)
            } else {
              document.getElementById('mastodon-comments-list').innerHTML = 
              `<div class="admonition info">
                <p class="admonition-title">
                  No comments found. <a href="https://{{ config.extra.mastodon.host }}/@{{ config.extra.mastodon.user }}/{{ page.meta.comment_id }}">Be the first!</a>
                </p>
              </div>
              `;
            }
    
            commentsLoaded = true;
          });
      }
    
      function respondToVisibility(element, callback) {
        var options = {
          root: null,
        };
    
        var observer = new IntersectionObserver((entries, observer) => {
          entries.forEach(entry => {
            if (entry.intersectionRatio > 0) {
              callback();
            }
          });
        }, options);
    
        observer.observe(element);
      }
    
      var comments = document.getElementById("mastodon-comments-list");
      respondToVisibility(comments, loadComments);
    </script>
  {% else %}
    <div class="admonition warning">
      <p class="admonition-title">
        No Mastodon post configured for this page. Contact {{ config.site_author | default('the post author', true) }} if you want to comment here.
      </p>
    </div>
  {% endif %}
{% endif %}

comments.css

:root{
  --mastodon-comment-indent: 40px;
  --mastodon-comment-border-radius: 3px;
  
  --mastodon-comment-bg-color: rgba(0, 0, 0, 0.2);
  --mastodon-comment-border-color: rgba(0, 0, 0, 0.4);
  --mastodon-comment-user-color: #939393;
  
  --mastodon-comment-status--inactive: #5d686f;
  --mastodon-comment-status-replies--active: #448aff;
  --mastodon-comment-status-favourite--active: #ff9100;
  --mastodon-comment-status-reblog--active: #00c853;
}

@media only screen and (max-width: 1024px){
  :root{
    --mastodon-comment-indent: 20px;
  }
}

@media only screen and (max-width: 640px){
  :root{
    --mastodon-comment-indent: 0px;
  }
}

.mastodon-comment{
  background-color: var(--mastodon-comment-bg-color);
  border-radius: var(--mastodon-comment-border-radius);
  border: 1px var(--mastodon-comment-border-color) solid;
  padding: 20px;
  margin-bottom: 1.5rem;
  display: flex;
  flex-direction: column;
}

.mastodon-comment p{
  margin-bottom: 0px;
}

.mastodon-comment .content{
  margin: 15px 20px;
}

.mastodon-comment .content p:first-child{
  margin-top: 0;
  margin-bottom: 0;
}

.mastodon-comment .attachments{
  max-width: 0px 10px;
}

.mastodon-comment .attachments > *{
  max-width: 0px 10px;
}

.mastodon-comment .author{
  padding-top: 0;
  display: flex;
}

.mastodon-comment .author a{
  text-decoration: none;
}

.mastodon-comment .author .avatar img{
  margin-right: 1rem;
  min-width: 60px;
  border-radius: 5px;
}

.mastodon-comment .author .details{
  display: flex;
  flex-direction: column;
}

.mastodon-comment .author .details .name{
  font-weight: bold;
}

.mastodon-comment .author .details .user{
  color: var(--mastodon-comment-user-color);
}

.mastodon-comment .author .date{
  margin-left: auto;
  font-size: small;
}

.mastodon-comment .status > div{
  display: inline-block;
  margin-right: 15px;
}

.mastodon-comment .status a{
  color: var(--mastodon-comment-status--inactive);
  text-decoration: none;
}

.mastodon-comment .status .twemoji.replies.active a{
  color: var(--mastodon-comment-status-replies--active);
}

.mastodon-comment .status .twemoji.reblogs.active a{
  color: var(--mastodon-comment-status-reblog--active);
}

.mastodon-comment .status .twemoji.favourites.active a{
  color: var(--mastodon-comment-status-favourite--active);
}

.mastodon-comment .status svg{
  margin-right: 0.2rem;
  vertical-align: middle;
}

Final steps

What is left to do is add the necessary data to the mkdocs.yml file and the pages you want comments for.

In the mkdocs.yml you need to add the following:

extra:
  mastodon:
    user: example     # Replace with your account name
    host: example.com # Replace with the instance you use

Q: Why not include this in the comments.html?
A: I've chosen this setup as it would allow a relatively easy adjustment for the case of you switching instances.

On the pages you want to have comments enabled, you need to add these frontmatter options:

• comments: true to enable the comments feature. Only needed if you're not enabling it by default (i.e. by not including the if check in the partials file or by using the meta plugin to enable it for a folder)
• comment_id: <id> with <id> being an id to a valid post on the Mastodon instance and from the user you defined in your mkdocs.yml file.

This should be everything and once you publish your pages (or check them in the live preview using mkdocs serve) should the comment system load your posts or otherwise show admonition boxes with further info.

Preview

Here are some previews to show you how it may look like.

No post configured

No replies

Comment

Footnotes

1. https://github.com/squidfunk/mkdocs-material ↩

2. https://paste.gg/p/Andre601/4d1323b59c35421e90bcdc79f6ed8ff2 ↩

3. https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme ↩

[squidfunk]

Awesome, thanks for sharing!