New function: Add Utterances script

[mccarthy-m-g]

Continuing our conversation from the end of PR #12:

A wrapper function to create the HTML file for injecting an Utterances comment section into distill posts would be a nice addition to distilltools. Users would still have to do some additional work manually, but this would make creating the script easier, and also make some of the configuration options such as theming more explicit.

Here is the HTML script we would wrap. I've put # argument next to lines we would turn into arguments in the R function.

<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", "user/repo"); # argument
   script.setAttribute("issue-term", "title"); # argument
   script.setAttribute("crossorigin", "anonymous");
   script.setAttribute("label", "utterances"); # argument
   script.setAttribute("theme", "github-light"); # argument

   /* wait for article to load, append script to article element */
   var observer = new MutationObserver(function (mutations, observer) {
     var article = document.querySelector("details.comment-section"); # argument
     if (article) {
       observer.disconnect();
       /* HACK: article scroll */
       article.setAttribute("style", "overflow-y: hidden");
       article.appendChild(script);
     }
   });

   observer.observe(document.body, { childList: true });
 });
</script>

I'm thinking we could use the htmltools package to wrap the script, then we can save it to a file with htmltools::save_html().

The R function API would look something like this. The last five arguments correspond to the # arguments in the HTML script above. Providing a vector for issue_term and theme makes it easier for users to see the available options for those, and we can prevent invalid choices that way (whether we should restrict invalid choices or pass them through is worth thinking about though, since we would have to update the theme vector whenever Utterances adds a new theme if we go with the former choice).

utterances(
  file,
  repo,
  issue_term = c("pathname", "url", "title", "og:title", ...),
  label,
  theme = c("github-light", "github-dark", "icy-dark", ...),
  selector
)

This function would write the HTML script wherever the users specifies with file. They would then have to go through some steps manually to enable the comments section. So we would need to also give some direction there (I liked your idea of drawing inspiration from usethis here).

I think writing the code for the function will be simple, so the big points for discussion are the API and the additional guidance we give users. Maybe also whether we should make note of how to place the comment section inside a collapsible <details> tag (and whether we should create this or leave it to the user).

[EllaKaye]

Hi Michael,

Thanks so much for this, and apologies for the delayed response (as I mentioned at the close of #12, I've got a lot else going on right now - I hope your thesis is going well in the meantime!)

I think this would be a fab addition to {distilltools} and everything you've said above makes sense. Using {htmltools} seems like a sensible approach. I'm not familiar with JavaScript (though planning to learn once my PhD is done!) so I won't be the best person to troubleshoot issues, but, as you say, hopefully the function itself will be pretty straightforward.

I like the idea of providing vectors for issue_term and theme for the reasons you say. To save from having to update the vector when GitHub updates options, if an invalid choice is given, I'd lean towards reverting to a default and providing a warning or message, rather than having the function fail with an error.

Putting comments in a collapsible <details> tag is a really nice feature, so would definitely be good to think about if and how we can make that available. How we decide to handle something that requires css is something that'll have ramifications for future functions in {distilltools} too - I imagine this will come up a lot in a package that provides tools for styling websites! At the moment my thoughts lean towards one function for the html and a supporting function for the css. I can envisage functions where the user will want to include the html in multiple places (like the icon_link function), but the css only needs writing once, but we can discuss (at the moment icon_link doesn't have a corresponding css function, but it's something I'm thinking about).

I'm not sure if this is going to be a problem for this function, but I have an issue with Utterances on my distill website that I raised as an issue on the distill GitHub but which is unresolved there. Is this something that you've come across on your site?

Also, I have a tiny tweak to Miles's script to allow comments on my talks as well as blogs. Do we want to allow another argument that allows users to specify which collections they want to activate comments for (which defaults just to posts)?