docs: add giscus comments system (#96)

* chore: rename comment to comments

* docs: add giscus comments

* docs: update

exampleSite/content/docs/advanced/_index.md

@@ -12,4 +12,5 @@ This section covers some advanced topics of the theme.
 {{< cards >}}
   {{< card link="multi-language" title="Multi-language" icon="translate" >}}
   {{< card link="customization" title="Customization" icon="pencil" >}}
+  {{< card link="comments" title="Comments System" icon="chat-alt" >}}
 {{< /cards >}}

exampleSite/content/docs/advanced/comments.md

@@ -0,0 +1,39 @@
+---
+title: Comments System
+linkTitle: Comments
+---
+
+Hextra supports adding comments system to your site.
+Currently [giscus](https://giscus.app/) is supported.
+
+<!--more-->
+
+## giscus
+
+[giscus](https://giscus.app/) is a comments system powered by [GitHub Discussions](https://docs.github.com/en/discussions). It is free and open source.
+
+To enable giscus, you need to add the following to the site configuration file:
+
+```yaml {filename="hugo.yaml"}
+params:
+  comments:
+    enable: false
+    type: giscus
+
+    giscus:
+      repo: <repository>
+      repoId: <repository ID>
+      category: <category>
+      categoryId: <category ID>
+```
+
+The giscus configurations can be constructed from the [giscus.app](https://giscus.app/) website. More details can also be found there.
+
+Comments can be enabled or disabled for a specific page in the page front matter:
+
+```yaml {filename="content/docs/about.md"}
+---
+title: About
+comments: true
+---
+```

exampleSite/hugo.yaml

@@ -124,19 +124,19 @@ params:
     enable: true
     base: "https://github.com/imfing/hextra/edit/main/exampleSite/content"
 
-  comment:
+  comments:
     enable: false
     type: giscus
 
     # https://giscus.app/
     giscus:
-      repo: "imfing/hextra"
+      repo: imfing/hextra
-      repoId: "R_kgDOJ9fJag"
+      repoId: R_kgDOJ9fJag
-      category: "General"
+      category: General
-      categoryId: "DIC_kwDOJ9fJas4CY7gW"
+      categoryId: DIC_kwDOJ9fJas4CY7gW
-      # mapping: "pathname"
+      # mapping: pathname
       # strict: 0
       # reactionsEnabled: 1
       # emitMetadata: 0
-      # inputPosition: "top"
+      # inputPosition: top
-      # lang: "en"
+      # lang: en

layouts/_default/list.html

@@ -10,7 +10,7 @@
         </div>
         <div class="mt-16"></div>
         {{ partial "components/last-updated.html" . }}
-        {{ partial "components/comment.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

layouts/_default/single.html

@@ -10,7 +10,8 @@
         <div class="content">
           {{ .Content }}
         </div>
-        {{ partial "components/comment.html" . }}
+        <div class="mt-16"></div>
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

layouts/blog/single.html

@@ -28,7 +28,7 @@
         {{ partial "components/last-updated.html" . }}
         {{ .Scratch.Set "reversePagination" true }}
         {{ partial "components/pager.html" . }}
-        {{ partial "components/comment.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

layouts/docs/list.html

@@ -9,10 +9,9 @@
           <h1>{{ .Title }}</h1>
           {{ .Content }}
         </div>
-        <div class="mt-16"></div>
         {{ partial "components/last-updated.html" . }}
         {{ partial "components/pager.html" . }}
-        {{ partial "components/comment.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

layouts/docs/single.html

@@ -11,7 +11,7 @@
         </div>
         {{ partial "components/last-updated.html" . }}
         {{ partial "components/pager.html" . }}
-        {{ partial "components/comment.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

layouts/partials/components/comment.html

@@ -1,8 +0,0 @@
-{{- $commentEnable := site.Params.comment.enable | default false -}}
-{{- $commentPageEnable := .Params.comment | default true -}}
-
-{{- if and $commentEnable $commentPageEnable -}}
-  {{- if eq site.Params.comment.type "giscus" -}}
-    {{ partial "components/giscus.html" . }}
-  {{- end -}}
-{{- end -}}

layouts/partials/components/comments.html

@@ -0,0 +1,11 @@
+{{- $enableComments := site.Params.comments.enable | default false -}}
+
+{{ if not (eq .Params.comments nil) }}
+  {{ $enableComments = .Params.comments }}
+{{ end }}
+
+{{- if $enableComments -}}
+  {{- if eq site.Params.comments.type "giscus" -}}
+    {{ partial "components/giscus.html" . }}
+  {{- end -}}
+{{- end -}}

layouts/partials/components/giscus.html

@@ -1,6 +1,6 @@
 {{- $lang := site.Language.LanguageCode | default `en` -}}
 
-{{- with site.Params.comment.giscus -}}
+{{- with site.Params.comments.giscus -}}
 <script>
   /*
    * "preferred color scheme" theme in giscus works using "prefers-color-scheme" in media query.
@@ -57,4 +57,6 @@
 </script>
 
 <div id="giscus"></div>
+{{- else -}}
+  {{ warnf "giscus is not configured" }}
 {{- end -}}