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).
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
# argumentnext to lines we would turn into arguments in the R function.I'm thinking we could use the
htmltoolspackage to wrap the script, then we can save it to a file withhtmltools::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 forissue_termandthememakes 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).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 fromusethishere).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).