README.org (2836B)
1 * Hyperskip
2 Hyperskip adds email-powered static comments for Hugo.
3
4 ** Usage
5 *** Installation
6 Clone this repository to your themes folder (typically =themes= from Hugo root),
7 and add Hyperskip to the list of themes (yes, you can use a list of theme names)
8 in Hugo configuration. Here's an example when using TOML format config
9 (=config.toml=):
10 #+BEGIN_SRC toml
11 theme = ["hugo-djem-so", "hugo-hyperskip"]
12 #+END_SRC
13
14 In template files, insert comment section with
15 #+BEGIN_SRC html
16 {{ partial "hyperskip.html" . }}
17 #+END_SRC
18 This would insert both a =mailto= form for comment submissions, and the list of
19 comments.
20
21 For best compatibility with web feeds like RSS or ATOM, use the following to
22 avoid including =<script>= and =<form>= when inserting comments to web feed
23 templates
24 #+BEGIN_SRC html
25 {{ partial "hyperskip_feed.html" . }}
26 #+END_SRC
27
28 *** Comment Format
29 The theme expects to find =data/comments.toml= in Hugo directory with the
30 following format:
31 #+BEGIN_SRC toml
32 [[comments]]
33 name="Anonymous"
34 email_hash="1234abcd8d"
35 time=2020-01-01T01:01:01+00:00
36 uri="/my-first-post/"
37 content="""
38 Hello!
39 """
40 [[comments]]
41 name="Ken"
42 email_hash="abcd1234h8"
43 time=2020-01-01T01:03:01+00:00
44 uri="/my-first-post/"
45 content="""
46 Thanks!
47 """
48 #+END_SRC
49
50 Due to the linear nature of the way comments are stored, replies are handled by
51 including an anchor link (or multiple ones) to the comment(s) being replied
52 to. The structure of comments is thus an directed acyclic graph, instead of a
53 tree. Anchor links are generated from MD5 hash of author name and timestamp,
54 both of which are already public information.
55
56 For the =mailto= form to work properly, please specify in Hugo configuration
57 author's email, which will be used for submission and matching blog author's
58 comments. For example, when using TOML format config (=config.toml=), you can
59 specify author information like so:
60 #+BEGIN_SRC toml
61 [author]
62 email = "author@example.com"
63 #+END_SRC
64
65 The last 4 characters of =email_hash= will be displayed on the page for anyone
66 aside from the blog author (SHA256 is used to match author email to given email
67 hash). It is preferable to also only store the last few characters of email hash
68 in the =comments.toml= file. This is used as an alternative to services like
69 Gravatar or Libravatar for identification purposes, which would have required
70 storing the entire hash value, an inherent security risk.
71
72 By default, form data is sent using URL encoding in body of the email. An easy
73 way to convert it back is to use =urllib.parse.unquote= in Python.
74
75 *** Webmention
76 Hyperskip also includes a form for submitting Webmentions. To enable it, specify
77 Webmention endpoint in your site's =config.toml= (or equivalent) like so:
78 #+BEGIN_SRC toml
79 [params]
80 webmentionEndpoint = "https://your-webmention-endpoint/"
81 #+END_SRC