Enable utterances with distill

Interested in giving your readers the ability to comment on your {distill} blog? Look no further than utteranc.es.

Note: This post was originally written by Vebash Naidoo and copied here on March 16, 2021 - see the original post here for a potentially updated version.

Allow readers to comment on your blog posts

You may be interested, like I was, in allowing reader comments for your {distill} blog posts.

Upon researching the best way, I found that there was some negativity towards some comment platforms, and heard that utterances was a good alternative for now. Thanks go to Maëlle Salmon - during her session on blogging, for R-Ladies Johannesburg, she used utterances on her teaching site, and also taught us about it.

Acknowledgements

I’d like to make my acknowledgements up front, because this post is just a synthesis of two excellent posts from Maëlle Salmon and Miles McBain.

• Goodbye Disqus! Hello, Utterances
• How I got utteranc.es working on my rmarkdown distill blog
• This distill issue, was also a big help. Thanks to Taras Kaduk.

Reading their posts will give you the tools you need to have comments on your blog posts using utterances. The below is a summary from these resources.

utterances

“utterances is a comments widget built on GitHub issues”.

1. To set it up you need to first install the utterances GitHub app, if you have not already done so.

2. You then need to allow the app access to your blog repository (repo) in GitHub. My blog repo is named Blog_Vebash (inspired, eh 🙊).

   

3. In GitHub, navigate to the Issues tab in your Blog’s repo, and open the Labels section as highlighted below.

   

4. Choose New label to add a label for the issue that will serve as your blog’s comments. I added mine as:

      comments 💬
    

   

HTML File in RStudio Project

We need to add an .html file that contains the information for the utterances app. Like Miles did, I named mine utterances.html.

1. Create an utterances.html file as shown below, with your blog repo details in the place of the one noted there. Here is mine, copied nearly directly from Mile’s.

    ```
    <script>
      document.addEventListener("DOMContentLoaded", function () {
        if (!/posts/.test(location.pathname)) {
          return;
        }
   
        var script = document.createElement("script");
        script.src = "https://utteranc.es/client.js";
        script.setAttribute("repo", "sciencificity/Blog_Vebash");
        script.setAttribute("issue-term", "title");
        script.setAttribute("crossorigin", "anonymous");
        script.setAttribute("label", "comments 💬");
        script.setAttribute("theme", "github-light");
   
        /* wait for article to load, append script to article element */
        var observer = new MutationObserver(function (mutations, observer) {
          var article = document.querySelector("d-article");
          if (article) {
            observer.disconnect();
            /* HACK: article scroll */
            article.setAttribute("style", "overflow-y: hidden");
            article.appendChild(script);
          }
        });
   
        observer.observe(document.body, { childList: true });
      });
    </script>
    ```

You may also follow Taras Kaduk’s advice and amend the d-article, in the querySelector, to d-appendix, if you want your comments to appear after the appendix, instead of between the article and the appendix.

2. Place utterances.html in your main blog folder.

   

3. In your _site.yml file add the includes part under your output format YAML. Now comments using utterances is available for all your blog posts.

   output:
     distill::distill_article:
       includes:
         in_header: utterances.html

Someone commented 🎉

• To comment a reader has to log into their GitHub account, and give the utterances app permission.
• When a reader comments it opens a comment issue in your Blog’s GitHub repo via the utterances-bot.
• You may respond on your blog post directly, or in the GitHub repo’s Issues page.
• If you do it on the Issues page, you may also close the issue there.
• As Maëlle remarks the downside is perhaps that your reader needs a GitHub account. I am hopeful this will not be too big of a deterrent for readers. If it is, don’t hesitate to reach out on Twitter - I am interested to hear your opinion.

Happy {distill} Blogging

🕺