From e22b8d5c0e6252ca8b34429fcabd2e4294ddfe1a Mon Sep 17 00:00:00 2001
From: yuri <1969yuri1969@gmail.com>
Date: Fri, 13 Jun 2025 23:09:05 +0200
Subject: [PATCH] feat(tags): improve usability of tags (#698)

* feat(tags): improve usability of tags

* Tags can be shown also at docs
* Documented tag-related config flags
* Added example tags to the site
* Made rendered tags active

* Move tags listing to ToC

* Hide tags section on no tags
---
 exampleSite/content/docs/getting-started.md     |  3 +++
 exampleSite/content/docs/guide/configuration.md | 15 +++++++++++++++
 exampleSite/hugo.yaml                           |  3 +++
 layouts/_partials/tags.html                     |  7 +++++++
 layouts/_partials/toc.html                      |  9 +++++++++
 layouts/blog/list.html                          | 10 +++-------
 6 files changed, 40 insertions(+), 7 deletions(-)
 create mode 100644 layouts/_partials/tags.html

diff --git a/exampleSite/content/docs/getting-started.md b/exampleSite/content/docs/getting-started.md
index e25ca5c..22842fe 100644
--- a/exampleSite/content/docs/getting-started.md
+++ b/exampleSite/content/docs/getting-started.md
@@ -1,6 +1,9 @@
 ---
 title: Getting Started
 weight: 1
+tags:
+  - Docs
+  - Guide
 next: /docs/guide
 prev: /docs
 ---
diff --git a/exampleSite/content/docs/guide/configuration.md b/exampleSite/content/docs/guide/configuration.md
index 4530351..f7220e0 100644
--- a/exampleSite/content/docs/guide/configuration.md
+++ b/exampleSite/content/docs/guide/configuration.md
@@ -1,6 +1,8 @@
 ---
 title: Configuration
 weight: 2
+tags:
+  - Config
 ---
 
 Hugo reads its configuration from `hugo.yaml` in the root of your Hugo site.
@@ -228,6 +230,19 @@ params:
   dateFormat: "January 2, 2006"
 ```
 
+### Tags
+
+To display page tags, set following flags in the config file:
+
+```yaml {filename="hugo.yaml"}
+params:
+  blog:
+    list:
+      displayTags: true
+  toc:
+    displayTags: true
+```
+
 ### Page Width
 
 The width of the page can be customized by the `params.page.width` parameter in the config file:
diff --git a/exampleSite/hugo.yaml b/exampleSite/hugo.yaml
index 1ccc87a..596de75 100644
--- a/exampleSite/hugo.yaml
+++ b/exampleSite/hugo.yaml
@@ -178,6 +178,9 @@ params:
     article:
       displayPagination: true
 
+  toc:
+    displayTags: true
+
   highlight:
     copy:
       enable: true
diff --git a/layouts/_partials/tags.html b/layouts/_partials/tags.html
new file mode 100644
index 0000000..d67ed91
--- /dev/null
+++ b/layouts/_partials/tags.html
@@ -0,0 +1,7 @@
+<p class="hx:opacity-50 hx:text-sm hx:leading-7">
+{{- range $tag := .Params.tags -}}
+  {{- with $.Site.GetPage (printf "/tags/%s" $tag) -}}
+    <a class="hx:inline-block hx:mr-2" href="{{ .RelPermalink }}">#{{ .Title }}</a>
+  {{- end -}}
+{{- end -}}
+</p>
\ No newline at end of file
diff --git a/layouts/_partials/toc.html b/layouts/_partials/toc.html
index 0cc6c29..d55b5e9 100644
--- a/layouts/_partials/toc.html
+++ b/layouts/_partials/toc.html
@@ -2,6 +2,7 @@
 {{/* TODO: toc bottom part should be able to hide */}}
 {{- $toc := .Params.toc | default true -}}
 {{- $onThisPage := (T "onThisPage") | default "On this page"}}
+{{- $tags := (T "tags") | default "Tags"}}
 {{- $editThisPage := (T "editThisPage") | default "Edit this page"}}
 {{- $backToTop := (T "backToTop") | default "Scroll to top" -}}
 
@@ -18,6 +19,14 @@
       {{- end -}}
 
       {{- $borderClass := "hx:mt-8 hx:border-t hx:bg-white hx:pt-8 hx:shadow-[0_-12px_16px_white] hx:dark:bg-dark hx:dark:shadow-[0_-12px_16px_#111]" -}}
+
+      {{- if and site.Params.toc.displayTags .Params.tags -}}
+        <div class="{{ $borderClass }} hx:sticky hx:bottom-0 hx:flex hx:flex-col hx:items-start hx:gap-2 hx:border-gray-200 hx:dark:border-neutral-800 hx:contrast-more:border-t hx:contrast-more:border-neutral-400 hx:contrast-more:shadow-none hx:contrast-more:dark:border-neutral-400">
+          <p class="hx:mb-1 hx:font-semibold hx:tracking-tight">{{ $tags }}</p>
+          {{ partial "tags.html" . }}
+        </div>
+      {{- end -}}
+
       {{- if not .Fragments.Headings -}}
         {{- $borderClass = "" -}}
       {{- end -}}
diff --git a/layouts/blog/list.html b/layouts/blog/list.html
index 5b2cad1..5527ba8 100644
--- a/layouts/blog/list.html
+++ b/layouts/blog/list.html
@@ -11,13 +11,9 @@
         {{- range $pages }}
           <div class="hx:mb-10">
             <h3><a style="color: inherit; text-decoration: none;" class="hx:block hx:font-semibold hx:mt-8 hx:text-2xl " href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
-            {{- if site.Params.blog.list.displayTags -}}
-              {{ with .Params.tags }}
-                <p class="hx:opacity-50 hx:text-sm hx:leading-7">
-                  {{- range . }}<a class="hx:inline-block hx:mr-2">#{{ . }}</a>{{ end -}}
-                </p>
-              {{ end -}}
-            {{- end -}}
+            {{ if site.Params.blog.list.displayTags }}
+              {{ partial "tags.html" . }}
+            {{ end }}
             <p class="hx:opacity-80 hx:mt-4 hx:leading-7">{{- partial "utils/page-description" . -}}</p>
             <p class="hx:opacity-80 hx:mt-1 hx:leading-7">
               <a class="hx:text-[color:hsl(var(--primary-hue),100%,50%)] hx:underline hx:underline-offset-2 hx:decoration-from-font" href="{{ .RelPermalink }}">