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:

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


   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]


   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!

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

   {{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.


   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




  [1] "Static site generator", wikipedia,

  [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


Wang                                                            [Page 4]