Enable utterances with distill

github features tutorial utterances

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

Vebash Naidoo https://twitter.com/Sciencificity
2021-02-20

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.

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 🙊).

    Give utterances app access to your blog

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

    Add a label in Issues part I

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

       comments đź’¬
     

    Add a label in Issues part II

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>
     ```
  1. Place utterances.html in your main blog folder.

    Place your utterances.html file in your main blog folder

  2. 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 🎉

Happy {distill} Blogging

đź•ş

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY-SA 4.0. Source code is available at https://github.com/jhelvy/distillery, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".

Citation

For attribution, please cite this work as

Naidoo (2021, Feb. 20). The Distillery: Enable utterances with distill. Retrieved from https://distillery.rbind.io/posts/2021-02-19-enable-utterances-with-distill/

BibTeX citation

@misc{naidoo2021enable,
  author = {Naidoo, Vebash},
  title = {The Distillery: Enable utterances with distill},
  url = {https://distillery.rbind.io/posts/2021-02-19-enable-utterances-with-distill/},
  year = {2021}
}