Provide an ability to use comments form

CHANGELOG.md

@@ -29,6 +29,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   {{ with $siteAuthor.twitter }} {{ . }} {{ end }}
   {{ with $siteAuthor.location }} {{ . }} {{ end }}
   ```
+- Provided support for giscus comments, enabling interactive discussions on site
+  pages. This includes:
+  - A new JavaScript file (`giscus.js`) handling the dynamic loading of giscus
+    scripts based on site configuration.
+  - Configuration settings for giscus in the `exampleSite/config/_default/params.yaml`
+    to allow users to easily enable and configure giscus comments from the site's
+    parameters.
 
 ### Changed
 

assets/js/giscus.js

@@ -0,0 +1,37 @@
+import {
+  category,
+  categoryId,
+  emitMetadata,
+  inputPosition,
+  lang,
+  mapping,
+  reactionsEnabled,
+  repo,
+  repoId,
+  strict,
+  theme
+} from '@params';
+
+document.addEventListener('DOMContentLoaded', function () {
+  const giscusAttributes = {
+    'src': 'https://giscus.app/client.js',
+    'data-repo': repo,
+    'data-repo-id': repoId,
+    'data-category': category,
+    'data-category-id': categoryId,
+    'data-mapping': mapping,
+    'data-strict': strict,
+    'data-reactions-enabled': reactionsEnabled,
+    'data-emit-metadata': emitMetadata,
+    'data-input-position': inputPosition,
+    'data-theme': theme,
+    'data-lang': lang,
+    'crossorigin': 'anonymous',
+    'async': ''
+  };
+
+  // Dynamically create script tag
+  const giscusScript = document.createElement('script');
+  Object.entries(giscusAttributes).forEach(([key, value]) => giscusScript.setAttribute(key, value));
+  document.getElementById('giscus').appendChild(giscusScript);
+});

exampleSite/config/_default/params.yaml

@@ -123,3 +123,26 @@ search:
     # - it
     # - pt
     # - ru
+
+comments:
+  enable: false
+  type: giscus
+
+  # Configure giscus comments.
+  #
+  # For more see: https://giscus.app/
+  giscus:
+    # Required parameters:
+    repo: sergeyklay/gohugo-theme-ed
+    repoId: R_kgDOHEYacw
+    category: General
+    categoryId: DIC_kwDOHEYac84Cerse
+
+    # Optional parameters:
+    theme: light
+    mapping: pathname
+    strict: 0
+    reactionsEnabled: 1
+    emitMetadata: 0
+    inputPosition: bottom
+    lang: en

exampleSite/content/documentation/index.md

@@ -295,6 +295,108 @@ The internal links pointing to the right sections in your document are generated
 
 ---
 
+## Comments
+
+Ed theme now supports adding a comments system to your site, enhancing interactive engagement. Currently, the theme supports integration with {{< link src="https://giscus.app/" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}giscus{{< /link >}}.
+
+### giscus
+
+{{< link src="https://giscus.app/" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}giscus{{< /link >}} is a comments system powered by {{< link src="https://docs.github.com/en/discussions/" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}GitHub Discussions{{< /link >}}. It leverages GitHub's infrastructure to provide a free, open source platform for comments.
+
+giscus operates by linking your website's comment section directly to GitHub Discussions. Here’s an overview of the process:
+- When a page with giscus integration loads, it uses the {{< link src="https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions#search" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}GitHub Discussions search API{{< /link >}} to locate a discussion that matches the page. The association is determined based on a chosen mapping strategy such as URL, pathname, or the page's `<title>`.
+- If no existing discussion matches the page, giscus is configured to automatically create a new discussion when a visitor posts the first comment or reaction. This ensures that each page can have its own dedicated discussion thread, even if one was not previously set up manually.
+- To post a comment, visitors must authorize the giscus application via the GitHub OAuth flow, which grants the app permission to {{< link src="https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}post comments on their behalf{{< /link >}}. This authorization is a straightforward process, typically requiring just a few clicks to connect a GitHub account.
+- Alternatively, visitors can choose to comment directly within the GitHub Discussions platform. This flexibility allows users familiar with GitHub to engage in the discussion using an interface they are comfortable with.
+- All comments posted through giscus are hosted and moderated on GitHub, leveraging GitHub's native tools for managing discussions. This integration allows site owners to manage comments using the same workflows they use for other GitHub activities, providing a seamless moderation experience.
+
+Integrating giscus not only activates the dynamic interaction capabilities of GitHub Discussions on your Hugo site but also simplifies the management of user comments and engagements.
+
+To enable giscus in your Hugo site, you must first add configuration settings in the site's YAML configuration file (`config/_default/params.yaml`). Below is a template for setting up giscus, which includes enabling the system and specifying necessary identifiers that link your site with the giscus service:
+
+To enable giscus, you need to add the following to the site configuration file:
+
+~~~ yaml
+comments:
+  enable: true  # Set to false to disable comments globally
+  type: giscus
+
+  giscus:
+    # Required parameters:
+    # Replace with your repository
+    repo: 'your-github-username/repository-name'
+    # Repository ID from giscus setup
+    repoId: 'repository-ID'
+    # Discussion category
+    category: 'Announcements'
+    # Category ID from giscus setup
+    categoryId: 'category-ID'
+
+    # Optional parameters:
+    #
+    # ...
+~~~
+
+You can obtain the `repoId` and `categoryId` by configuring your repository on the {{< link src="https://giscus.app/" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}giscus setup page{{< /link >}}. More details can also be found there.
+
+#### Enabling/Disabling Comments on Individual Pages
+
+Comments can be enabled or disabled on a per-page basis using the front matter of individual pages. Here's how you can enable comments for a specific page:
+
+~~~ yaml
+---
+title: About
+comments: true
+---
+~~~
+
+#### Styling Comments
+
+By default, giscus will inherit the styling from your GitHub discussion forum. However, you can customize the appearance to better fit your site's design by specifying a `theme` parameter in the giscus configuration block:
+
+~~~ yaml
+comments:
+  # ...
+
+  giscus:
+    # Required parameters:
+    #
+    # ...
+
+    # Optional parameters:
+    # Available themes: cobalt, dark, light, dark, purge, etc.
+    theme: dark_dimmed
+~~~
+
+Refer to the {{< link src="https://github.com/giscus/giscus/blob/main/ADVANCED-USAGE.md#data-theme" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}giscus theme documentation{{< /link >}} for more details on available themes.
+
+#### Localization
+
+giscus supports multiple languages, and you can set the desired language for your comments section through the `lang` parameter:
+
+
+~~~ yaml
+comments:
+  # ...
+
+  giscus:
+    # Required parameters:
+    #
+    # ...
+
+    # Optional parameters:
+    # Use language codes like 'en' for English, 'es' for Spanish, etc.
+    lang: fr
+~~~
+
+---
+
+This enhancement to the Ed theme allows you to leverage the power of community discussions directly on your site, making it more dynamic and engaging for visitors.
+
+For more information on giscus, visit the {{< link src="https://giscus.app/" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}giscus website{{< /link >}}.
+
+---
+
 ## Getting help
 
 That should do it. If you have suggestions on how to improve Ed, make sure to leave us a line on {{< link src="https://github.com/sergeyklay/gohugo-theme-ed/issues" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}our issues page{{< /link >}}, or send us a pull request. If you run into an issue that isn't answered by this documentation or the `{{< link src="https://github.com/sergeyklay/gohugo-theme-ed/tree/main/exampleSite" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}exampleSite{{< /link >}}`, then visit the {{< link src="https://discourse.gohugo.io/" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}Hugo forum{{< /link >}}. The folks there are helpful and friendly. **Before** asking your question, be sure to read the {{< link src="https://discourse.gohugo.io/t/requesting-help/9132" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}requesting help guidelines{{< /link >}}. Feel free to tag me in your question, my forum username is {{< link src="https://discourse.gohugo.io/u/egrep/summary" class="external" target="_blank" hreflang="en" rel="noopener noreferrer" >}}@egrep{{< /link >}}.

layouts/_default/single.html

@@ -22,5 +22,7 @@ <h1 class="text-title">
     {{ if not (in (slice "drama" "narrative" "poem") $postType) }}
         {{ partial "post-tags.html" . }}
     {{ end }}
+
+    {{ partial "comments.html" . }}
 </article>
 {{ end }}

layouts/partials/comments.html

@@ -0,0 +1,39 @@
+{{- $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" -}}
+        {{- $isProduction := (or (eq (getenv "HUGO_ENV") "production") (eq site.Params.env "production")) -}}
+
+        {{- $repo := site.Params.comments.giscus.repo -}}
+        {{- $repoId := site.Params.comments.giscus.repoId -}}
+        {{- $category := site.Params.comments.giscus.category -}}
+        {{- $categoryId := site.Params.comments.giscus.categoryId -}}
+        {{- $theme := site.Params.comments.giscus.theme | default "light" -}}
+        {{- $emitMetadata := site.Params.comments.giscus.emitMetadata | default 0 -}}
+        {{- $inputPosition := site.Params.comments.giscus.inputPosition | default "bottom" -}}
+        {{- $lang := site.Params.comments.giscus.lang | default "en" -}}
+        {{- $mapping := site.Params.comments.giscus.mapping | default "pathname" -}}
+        {{- $reactionsEnabled := site.Params.comments.giscus.reactionsEnabled | default 1 -}}
+        {{- $strict := site.Params.comments.giscus.strict | default 0 -}}
+        {{- $commentsParams := dict "repo" $repo "repoId" $repoId "category" $category "categoryId" $categoryId "theme" $theme "emitMetadata" $emitMetadata "inputPosition" $inputPosition "lang" $lang "mapping" $mapping "reactionsEnabled" $reactionsEnabled "strict" $strict -}}
+
+        {{- $siteComments := slice -}}
+        {{- $siteComments = $siteComments | append (resources.Get "js/giscus.js") -}}
+        {{- $siteComments = $siteComments | resources.Concat "js/giscus-bundle.js" -}}
+
+        {{- $siteComments = $siteComments | js.Build (dict "format" "iife" "minify" $isProduction "target" "es2015" "params" $commentsParams) -}}
+
+        {{- if or (site.Params.assets.disable_fingerprinting) (not $isProduction) }}
+            <script src="{{ $siteComments.RelPermalink }}"></script>
+        {{- else -}}
+            {{- $siteComments = $siteComments | fingerprint }}
+            <script src="{{ $siteComments.RelPermalink }}" integrity="{{ $siteComments.Data.Integrity }}"></script>
+        {{- end -}}
+
+        <div id="giscus"></div>
+    {{- end -}}
+{{- end -}}

theme.toml

@@ -27,6 +27,7 @@ tags = [
 features = [
   "blog",
   "clean",
+  "comments form",
   "contact form",
   "favicon",
   "jsonfeed",