taxonomy: modularize term list generation #671

exampleSite/content/basics/migration/_index.en.md

@@ -18,6 +18,12 @@ This document shows you what's new in the latest release. For a detailed list of
 
 ---
 
+## 5.23.0 (2023-10-03) {#5230}
+
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to print custom taxonomies anywhere in you page. [See the docs]({{% relref "cont/taxonomy#customization" %}}).
+
+---
+
 ## 5.22.0 (2023-10-02) {#5220}
 
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} This release fixes an issue where in unfortunate conditions DOM ids generated by Hugo may collide with DOM ids set by the theme. To avoid this, all theme DOM ids are now prefixed with `R-`.

exampleSite/content/cont/taxonomy.en.md

@@ -40,3 +40,24 @@ url = "/tags"
 name = "<i class='fas fa-list'></i> Categories"
 url = "/categories"
 ```
+
+## Customization
+
+If you define [custom taxonomies](https://gohugo.io/content-management/taxonomies/#configure-taxonomies) and want to display a list of them somewhere on your page (often in the `layouts/partials/content-footer.html`) you can call a partial that does the job for you:
+
+````markdown
+{{- partial "term-list.html" (dict
+  "page" .
+  "taxonomy" "categories"
+  "icon" "list"
+) }}
+````
+
+### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **page**              | _&lt;empty&gt;_ | Mandatory reference to the page. |
+| **taxonomy**          | _&lt;empty&gt;_ | The plural name of the taxonomy to display as used in your frontmatter. |
+| **class**             | _&lt;empty&gt;_ | Additional CSS classes set on the outermost generated HTML element. |
+| **icon**              | _&lt;empty&gt;_ | An optional [Font Awesome icon name]({{%relref "shortcodes/icon#finding-an-icon" %}}) set to the left of the list. |

layouts/partials/content-footer.html

@@ -4,14 +4,8 @@
               <i class='fas fa-calendar'></i> {{ . | time.Format ":date_medium" }}
   {{- end }}
 {{- end }}
-{{- $page := . }}
+{{- partial "term-list.html" (dict
-{{- if .Params.categories }}
+  "page" .
-              <i class='fas fa-list'></i>
+  "taxonomy" "categories"
-  {{- $terms := slice | append .Params.categories }}
+  "icon" "list"
-  {{- range $idx, $term := sort $terms }}
+) }}
-    {{- with ($page.Site.GetPage (printf "%s%s" ("/categories/" | relURL) ($term | plainify | anchorize)) | default ($page.Site.GetPage (printf "%s%s" ("/categories/" | relURL) ($term | urlize)))) }}
-      {{- $to := . }}
-              {{ if gt $idx 0 }} | {{ end }}<a class="tag-link" href="{{ partial "relLangPrettyUglyURL.hugo" (dict "to" $to) }}">{{ $term }}</a>
-    {{- end }}
-  {{- end }}
-{{- end }}

layouts/partials/tags.html

@@ -1,13 +1,6 @@
 
-{{- $page := . }}
+{{- partial "term-list.html" (dict
-{{- if .Params.tags }}
+  "page" .
-<div class="tags">
+  "taxonomy" "tags"
-  {{- $terms := slice | append .Params.tags }}
+  "class" "tags"
-  {{- range $term := sort $terms }}
+) }}
-    {{- with ($page.Site.GetPage (printf "%s%s" ("/tags/" | relURL) ($term | plainify | anchorize)) | default ($page.Site.GetPage (printf "%s%s" ("/tags/" | relURL) ($term | urlize)))) }}
-      {{- $to := . }}
-  <a class="tag-link" href="{{ partial "relLangPrettyUglyURL.hugo" (dict "to" $to) }}">{{ $term }}</a>
-    {{- end }}
-  {{- end }}
-</div>
-{{- end }}

layouts/partials/term-list.html

@@ -0,0 +1,38 @@
+{{- $page := .page }}
+{{- $taxonomy := .taxonomy }}
+{{- $class := .class }}
+{{- $icon := .icon | default "" }}
+{{- $icon = trim $icon " " }}
+{{- if and $icon (not (findRE ".*?\\bfa-\\w.*?" $icon)) }}
+  {{- $icon = printf "fa-fw fas fa-%s" $icon }}
+{{- end }}
+{{- $taxonomy_page := $page.Site.GetPage $taxonomy }}
+{{- $terms := slice | append (index $page.Params $taxonomy) }}
+{{- $term_pages := dict }}
+{{- range sort $terms }}
+  {{- $term := trim . " " }}
+  {{- if not $term }}
+    {{- continue }}
+  {{- end }}
+  {{- $term_key := ($term | plainify | anchorize) }}
+  {{- with $page.Site.GetPage (printf "%s/%s" $taxonomy $term_key) }}
+    {{- $term_pages = $term_pages | merge (dict $term_key .) }}
+  {{- end }}
+  {{- $term_key = ($term | urlize) }}
+  {{- with $page.Site.GetPage (printf "%s/%s" $taxonomy $term_key) }}
+    {{- $term_pages = $term_pages | merge (dict $term_key .) }}
+  {{- end }}
+{{- end }}
+{{- with $term_pages }}
+<div class=" taxononmy-{{ $taxonomy }} term-list {{ $class }}">
+  {{- if $icon }}
+  <i class="{{ $icon }}" title="{{ $taxonomy_page.Title }}"></i>
+  {{- end }}
+  <ul>
+  {{- range $term_page := . }}
+    {{- $to := . }}
+    <li><a class="term-link" href="{{ partial "relLangPrettyUglyURL.hugo" (dict "to" $to) }}">{{ $to.Title }}</a></li>
+  {{- end }}
+  </ul>
+</div>
+{{- end }}

static/css/format-print.css

@@ -138,7 +138,7 @@ h1 + .footline{
 #R-body .topbar-sidebar-divider {
     border-width: 0;
 }
-.tags {
+.term-list {
     display: none;
 }
 mark {

static/css/ie.css

@@ -711,17 +711,17 @@
 		color: rgba( 74, 74, 74, 1 ); /* var(--MAIN-TITLES-TEXT-color) */
 	}
 
-	#R-body .tags a.tag-link {
+	#R-body .tags a.term-link {
 		background-color: rgba( 125, 201, 3, 1 ); /* var(--TAG-BG-color) */
 		color: rgba( 255, 255, 255, 1 ); /* var(--MAIN-BG-color) */
 		margin-right: 16px;
 	}
 
-	#R-body .tags a.tag-link:before {
+	#R-body .tags a.term-link:before {
 		border-right-color: rgba( 125, 201, 3, 1 ); /* var(--TAG-BG-color) */
 	}
 
-	#R-body .tags a.tag-link:after {
+	#R-body .tags a.term-link:after {
 		background: rgba( 255, 255, 255, 1 ); /* var(--MAIN-BG-color) */
 	}
 

static/css/tags.css

@@ -1,11 +1,15 @@
 /* Tags */
 
 .tags{
-    margin-left:1rem;
+    margin-left: 1rem;
-    margin-top:1rem;
+    margin-top: 1rem;
 }
 
-#R-body .tags a.tag-link {
+.tags.term-list li ~ li:before {
+    content: none
+}
+
+#R-body .tags a.term-link {
     border-bottom-right-radius: 3px;
     border-top-right-radius: 3px;
     box-shadow: 0 1px 2px rgba( 0, 0, 0, .2 );
@@ -19,7 +23,7 @@
     position: relative;
 }
 
-#R-body .tags a.tag-link:before {
+#R-body .tags a.term-link:before {
     border-color: transparent;
     border-style: solid;
     border-width: 1em 1em 1em 0;
@@ -31,7 +35,7 @@
     width: 0;
 }
 
-#R-body .tags a.tag-link:after {
+#R-body .tags a.term-link:after {
     border-radius: 100%;
     content: "";
     left: 1px;
@@ -41,6 +45,6 @@
     width: 5px;
 }
 
-#R-body .tags a.tag-link:hover:after {
+#R-body .tags a.term-link:hover:after {
     width: 5px;
 }

static/css/theme.css

@@ -2189,3 +2189,13 @@ html[dir="rtl"] #R-sidebar ul.collapsible-menu > li > label > i.fa-chevron-right
 #R-topics {
     padding-top: 1rem;
 }
+
+.term-list ul,
+.term-list li {
+    list-style: none;
+    display: inline;
+    padding: 0;
+}
+.term-list li ~ li:before {
+    content: " | "
+}

static/css/variant.css

@@ -372,16 +372,16 @@ pre:not(.mermaid) .copy-to-clipboard-button:hover {
     --VARIABLE-BOX-TEXT-color: var(--VARIABLE-BOX-CAPTION-color);
 }
 
-#R-body .tags a.tag-link {
+#R-body .tags a.term-link {
     background-color: var(--INTERNAL-TAG-BG-color);
     color: var(--INTERNAL-MAIN-BG-color);
 }
 
-#R-body .tags a.tag-link:before {
+#R-body .tags a.term-link:before {
     border-right-color: var(--INTERNAL-TAG-BG-color);
 }
 
-#R-body .tags a.tag-link:after {
+#R-body .tags a.term-link:after {
     background-color: var(--INTERNAL-MAIN-BG-color);
 }