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]