docs: add giscus comments system (#96)

* chore: rename comment to comments * docs: add giscus comments * docs: update
imfing · Sep 26, 2023 · 46dea71 · 46dea71
1 parent adf5a11
commit 46dea71
Show file tree

Hide file tree

Showing 11 changed files with 68 additions and 23 deletions.
diff --git a/exampleSite/content/docs/advanced/_index.md b/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 >}}
diff --git a/exampleSite/content/docs/advanced/comments.md b/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
+---
+```
diff --git a/exampleSite/hugo.yaml b/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"
-      repoId: "R_kgDOJ9fJag"
-      category: "General"
-      categoryId: "DIC_kwDOJ9fJas4CY7gW"
-      # mapping: "pathname"
+      repo: imfing/hextra
+      repoId: R_kgDOJ9fJag
+      category: General
+      categoryId: DIC_kwDOJ9fJas4CY7gW
+      # mapping: pathname
       # strict: 0
       # reactionsEnabled: 1
       # emitMetadata: 0
-      # inputPosition: "top"
-      # lang: "en"
+      # inputPosition: top
+      # lang: en
diff --git a/layouts/_default/list.html b/layouts/_default/list.html
@@ -10,7 +10,7 @@ <h1>{{ .Title }}</h1>
         </div>
         <div class="mt-16"></div>
         {{ partial "components/last-updated.html" . }}
-        {{ partial "components/comment.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

diff --git a/layouts/_default/single.html b/layouts/_default/single.html
@@ -10,7 +10,8 @@ <h1 class="text-center mt-2 text-4xl font-bold tracking-tight text-slate-900 dar
         <div class="content">
           {{ .Content }}
         </div>
-        {{ partial "components/comment.html" . }}
+        <div class="mt-16"></div>
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

diff --git a/layouts/blog/single.html b/layouts/blog/single.html
@@ -28,7 +28,7 @@ <h1 class="mt-2 text-4xl font-bold tracking-tight text-slate-900 dark:text-slate
         {{ partial "components/last-updated.html" . }}
         {{ .Scratch.Set "reversePagination" true }}
         {{ partial "components/pager.html" . }}
-        {{ partial "components/comment.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

diff --git a/layouts/docs/list.html b/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>

diff --git a/layouts/docs/single.html b/layouts/docs/single.html
@@ -11,7 +11,7 @@ <h1>{{ .Title }}</h1>
         </div>
         {{ partial "components/last-updated.html" . }}
         {{ partial "components/pager.html" . }}
-        {{ partial "components/comment.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

diff --git a/layouts/partials/components/comment.html b/layouts/partials/components/comment.html
diff --git a/layouts/partials/components/comments.html b/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 -}}
diff --git a/layouts/partials/components/giscus.html b/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 -}}