Quarto Comments
“It takes humility to seek feedback. It takes wisdom to understand it, analyze it and appropriately act on it.” Stephen Covey.
Introduction
For people who use Quarto to build their websites, there are a few options for adding commenting functionality to their site. This allows your readers to engage with your site, leaving text or emoji feedback. Quarto currently offers built-in support for three commenting widgets. This article compares their functionality, linking to minimal implementations of each.
For full details on how to implement each solution, please consult the Quarto commenting documentation.
This article was written with Quarto 1.5.56. The solutions explored in this article are in development and may change in the future.
Intended Audience
Programmers with a working knowledge of quarto websites, considering options for adding commenting features to their site.
What You’ll Need
Hypothesis
Hypothesis is a great new, feature-rich, social annotation solution. It has a strong commitment to open source. After exploring its main features, I would suggest it is aimed at a broad audience with strong features for academic audiences, particularly cohorts of students that will benefit from group analysis of documents.
For users to interact with the Hypothesis interface, they will need to create an account and login, though this is not a painful process and will prevent excess spam on your site. An example of a minimal quarto website with Hypothesis enabled is below - feel free to test the commenting features yourself. Click on the arrow in the top-right hand corner to expand the Hypothesis user interface (UI). Code for the site is available on GitHub.
| Simple setup, just include the Hypothesis portion in your site’s YAML & render. |
| Private highlighting. |
| Private notetaking if you create a private group. Other members can be invited to participate. |
| Toggle on/off highlights and comments separately. |
| Annotations - linked specifically to a region of text in the article. |
| Page notes - applied to an entire page. |
| Annotations and page notes can be tagged with additional metadata. |
| Revisions are easy and built into the UI. |
| Collapsible UI is neat, reducing clutter. |
| Browser extension available. |
| Compatible with sites deployed from other repo-hosting solutions, eg GitLab, BitBucket. |
| I couldn’t get the embedding options to work (eg theme etc). |
| No emoji reactions. |
Utterances
Utterances uses GitHub Issues to store comment data. If you are deploying your site from GitHub and are not making good use of the repo issues, this could be a viable option. It’s important to note that your users will need a GitHub account and to authenticate in order to post comments on your site. Please consult the Utterances documentation for more information. In order to read and write issues on your repo, you do need to give the Utterances GitHub app permission to read and write repo metadata. Without doing this, the Utterances UI will appear on your site but will not function correctly. Code for A minimal Quarto site with Utterances is available on GitHub. The site can be viewed below.
| Either give it global access to all repos or selected repos. |
| User must sign into GitHub and authorise the Utterances app. |
| Markdown compatibility as per usual GitHub issues. |
| First comment on a page creates an issue, subsequent comments are added to the same issue. |
| Reactions to comments with emojis. |
| Every comment creates a GitHub issue on the repo – 1 per page of your site. Maybe a bit noisy for some. |
| Marking issues as closed does not remove them from the site. |
| Deleting the issue from the repo will remove the comment but may also mess up the mapping of comments to pages. May cause issues moderating. |
| Couldn’t get the labels feature to work, despite creating the issue label of the same name, as the documentation suggested. |
| Cannot respond to a comment with text. |
| Revisions are possible though are not achievable through the website UI. By navigating to the repo issues, you can edit any comment that was authored by your account. |
Giscus
Giscus emulates the Utterances functionality, but by using the new(ish) GitHub Discussions feature as the comment database, instead of the repo issues. The Giscus documentation currently states the widget is in development, as well as the GitHub API that it relies on, so expect some changes with this solution. The Giscus documentation also provides a really useful tool that checks whether Giscus has been configured correctly on the target repo. This same tool was very useful in configuring the YAML metadata for my site correctly.
In the same way as Utterances, you will need to give the Giscus GitHub app permissions to read and write repo metadata. Users will also require a GitHub account in order to authenticate. Code for A minimal quarto site with Giscus is available on GitHub. The site can be viewed here (the Giscus interface will not render correctly within an iframe).
| Activate discussions on your repo or give it global access to all repos. |
| User must sign into GitHub and authorise the Giscus app. |
| Allows emoji reactions to articles or comments on articles. |
| Allows text responses to specific comments. |
| Markdown compatibility as per usual GitHub issues. |
| First comment on a page creates a GitHub Discussion, subsequent comments are added to the same Discussion. |
| Like Utterances, Giscus revisions are possible only through the GitHub UI. By navigating to the GitHub repo discussions tab, you can edit any post authored by your account. |
| Changing configuration (e.g., mapping: pathname to mapping: URL) will cause old Giscus comments to be lost from your site. Though they are still available in the repo under the discussions tab. |
Summary
Overall, I felt that Hypothesis offered the greatest functionality. However, it also presents a new service for your audience to subscribe to. If like me, your target audience consists mainly of programmers, then it is likely they will already have access to GitHub accounts and therefore one of the GitHub-specific solutions may present less of a barrier to your audience engaging with your content.
Comparing GitHub Utterances with Giscus, I considered the greater functionality and look of the Giscus UI to be just a little better than Utterances. Therefore I opted for this solution for this site, though I’ll keep it under review incase of breaking changes.
It’s great that the Quarto development team have implemented support for several commenting widgets. Although there are a great variety of alternative solutions available and implementing any of these solutions should be possible as quarto document metadata is fully customisable.
If you spot an error with this article, or have a suggested improvement then feel free to leave a comment (GitHub login required) or raise an issue on GitHub.
fin!