From 46dea718e62f9671bac0bfbb5815cdea9f1d221e Mon Sep 17 00:00:00 2001 From: Xin Date: Tue, 26 Sep 2023 23:33:27 +0100 Subject: [PATCH] docs: add giscus comments system (#96) * chore: rename comment to comments * docs: add giscus comments * docs: update --- exampleSite/content/docs/advanced/_index.md | 1 + exampleSite/content/docs/advanced/comments.md | 39 +++++++++++++++++++ exampleSite/hugo.yaml | 16 ++++---- layouts/_default/list.html | 2 +- layouts/_default/single.html | 3 +- layouts/blog/single.html | 2 +- layouts/docs/list.html | 3 +- layouts/docs/single.html | 2 +- layouts/partials/components/comment.html | 8 ---- layouts/partials/components/comments.html | 11 ++++++ layouts/partials/components/giscus.html | 4 +- 11 files changed, 68 insertions(+), 23 deletions(-) create mode 100644 exampleSite/content/docs/advanced/comments.md delete mode 100644 layouts/partials/components/comment.html create mode 100644 layouts/partials/components/comments.html diff --git a/exampleSite/content/docs/advanced/_index.md b/exampleSite/content/docs/advanced/_index.md index bade0671..cdcaed21 100644 --- 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 new file mode 100644 index 00000000..3327ee77 --- /dev/null +++ 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. + + + +## 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: + repoId: + category: + categoryId: +``` + +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 index 3dd11189..149bff2d 100644 --- 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 index 2cd87af3..c7559f70 100644 --- a/layouts/_default/list.html +++ b/layouts/_default/list.html @@ -10,7 +10,7 @@

{{ .Title }}

{{ partial "components/last-updated.html" . }} - {{ partial "components/comment.html" . }} + {{ partial "components/comments.html" . }} diff --git a/layouts/_default/single.html b/layouts/_default/single.html index 11c3bc49..01d98b86 100644 --- a/layouts/_default/single.html +++ b/layouts/_default/single.html @@ -10,7 +10,8 @@

{{ .Content }} - {{ partial "components/comment.html" . }} +
+ {{ partial "components/comments.html" . }} diff --git a/layouts/blog/single.html b/layouts/blog/single.html index c7059f50..5d8df163 100644 --- a/layouts/blog/single.html +++ b/layouts/blog/single.html @@ -28,7 +28,7 @@

diff --git a/layouts/docs/list.html b/layouts/docs/list.html index d4e9bbc7..5ffe82b8 100644 --- a/layouts/docs/list.html +++ b/layouts/docs/list.html @@ -9,10 +9,9 @@

{{ .Title }}

{{ .Content }} -
{{ partial "components/last-updated.html" . }} {{ partial "components/pager.html" . }} - {{ partial "components/comment.html" . }} + {{ partial "components/comments.html" . }} diff --git a/layouts/docs/single.html b/layouts/docs/single.html index 81656b5b..5ffe82b8 100644 --- a/layouts/docs/single.html +++ b/layouts/docs/single.html @@ -11,7 +11,7 @@

{{ .Title }}

{{ partial "components/last-updated.html" . }} {{ partial "components/pager.html" . }} - {{ partial "components/comment.html" . }} + {{ partial "components/comments.html" . }} diff --git a/layouts/partials/components/comment.html b/layouts/partials/components/comment.html deleted file mode 100644 index cb95e7ec..00000000 --- a/layouts/partials/components/comment.html +++ /dev/null @@ -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 -}} diff --git a/layouts/partials/components/comments.html b/layouts/partials/components/comments.html new file mode 100644 index 00000000..ac893a1b --- /dev/null +++ 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 index a0aeb578..8f7edf0f 100644 --- 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 -}}
+{{- else -}} + {{ warnf "giscus is not configured" }} {{- end -}}