Comments on static blogs - the right way [Prenote] I was about to write a blog post to introduce my "advanced" comment management system on this blog, and, I thought to myself: why don't I write this post in a RFC format? Well you know I'm not serious. It's Fun! This builds on top of a previous post: https://shrik3.com/post/static_comment And yet another useless skill learned - the format of a RFC memo.
Not affiliated T. Wang Request for Comments: [just for fun] December 2024 Email as Commenting System for Static Blogs Status of this Memo This memo proposes a email-based comment management scheme for static websites . This is meant for fun and not to be taken seriously. Distribution of this memo is unlimited. Table of Contents 1. Motivation ------------------------------------------- 1 2. Terminology ------------------------------------------ 2 3. Comment System via Emails ---------------------------- 3 4. Integration into static Blogs ------------------------ 3 5. Conventions ------------------------------------------ 3 6. Acknowledgments -------------------------------------- 4 7. References ------------------------------------------- 4 Motivation A static website (see Terminology), does not have a backend that changes the site's content after generation. For comments to work on such sites, a server software is typically required to collect, manage and distribute the comments. This server software can be either provided by a third party or selfhosted by the site owner. However 1) a third party brings privacy concerns and takes away data sovereign from both the commenter and the site owner. And 2) if the site owner hosts a comment management software themself, the purpose of hosting a static website is defeated. On the otherhand, there are two main approaches to display comments on a static website, i.e. to render a "comment section". One is to use Javascript to query the comment server for data and render the comments by modifying the DOM tree. Another is to directly open a viewpoint into another website with <iframe>. They are not desired by every web user and is not supported by every web browser (for example command line web browers such as w3m). Is there a convienent way to deliver the comments to the site owner securily without all the bloats? As it turns out, there is! Let's re-introduce our good old friend -- email. This is not a new idea, people do this all the time by reaching out to website owners via email to ask questions or exchange insights. However we'd like to give it a convention, so that people render those conversations into actual comments on the website, so that the other visitors can be enlighteneed. Wang [Page 1]
Terminology Static Site Generators (SSGs) are engines that use text input files (such as Markdown, reStructuredText, and AsciiDoc) to generate static web pages. Static sites generated by static site generators do not require a backend after site generation. [1] "Commenter" refers to a visitor of the website, who wishes to leave comments on a certain page. "Site owner" refers to the owner or administrator of the website, typically also the author of articles Comment System via Emails FORM & RelPermalink +-------------+ obtain +-----------+ | Static Site |--------------->| Commenter | +-------^-----+ mailto: uri +-----------+ | | Embed | | edit email body mailto: | | | +----v-----------+ Generate | Email Provider | | +--------^-------+ | | | | | | (direct reply) +---+-+ Automation +----v---+-------+ | SSG |<-------------------| Email client | +---+-+ +Moderation +----------------+ | (of the site owner) | Site source e.g. markdown Figure 1. Overlook of a comment system via Email. [TODO] illustration of this diagram. Integration into static Blogs The commenting-via-email is a convention, rather than a technical implementation. That is, a reader could reach out to the blog owner in any manner, and the site owner gives feed back by replying to the email and/or include the comments into the pages. A blog owner can embed a 'mailto' uri [2] into each blog page that is open for comment as shown in the following listing: <a href="mailto:{[addr]}?subject={{subj}&body={{txt}}"> click to send comment! </a> Wang [Page 2]
{{}} a pair of double curly brackets encloses a placeholder that is to be identified and replaced by the site generator. {{addr}} Email address of the site owner, which would receive comments. {{subj}} The subject field should contain a prefix and a page ID. A prefined prefix allows the site owner to efficiently identify and filter out the emails that contain comments. The page ID is unique to each page, thus linking the comment the page. The SSG should be about to generate and identify the page ID. {{txt}} The placeholder text of the email body. In pricinple the placeholding email body can be empty, however it's maybe a good idea to put a short piece of text to inform the commenter with e.g. term-of-use or instructions. It's up to the site owner how to integrate the received comments into the website. For example, it could be a email filter that parses the emails into a JSON [3] file in the following format: [ { "page" : "page_id_1", "content" : "comment_content", "datetime" :}, { "page" : "page_id_2", "content" : "comment_content", "datetime" : } ... ] The SSG then includes this JSON data during site (re)generation and renders the comment into its belonging page based on the page id. This scheme could also be expended to support a "in-reply-to" field, so that comments can be displayed in a tree style. As a fallback approach, the site owner can always chose to manually include the comments into their blog pages. Conventions The commenter should be informed with their rights and the term-of-use before the email is sent. The commenter should reserve the right to take down their comments. If the site owner decides that comments should not be taken down, or the site owner is unable to keep a record of the owning identities of each comment, such conditions should be agreed upon before the comments are published. Wang [Page 3]
The commenter's email address should not be disclosed without explicit permission. The site owner is not obliged to display the comment as is. The site owner reserve the rights to edit and/or reformat the comment content. However the displayed comments must be faithful to the original message. Acknowledgments TODO References [1] "Static site generator", wikipedia, https://en.wikipedia.org/wiki/Static_site_generator [2] M. Duerst et. al., "The 'mailto' URI Scheme", RFC 6068, IETF, October 2010. [3] T. Bray, Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, IETF, December 2017 [TODO] paging Wang [Page 4]