menu: more options to sort pages by #684

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

@@ -75,7 +75,7 @@ Note that some of these parameters are explained in details in other sections of
   customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
   # Hide Next and Previous page buttons displayed in topbar
   disableNextPrev = true
-  # Order sections in menu by "weight" or "title". Default to "weight";
+  # Order menu sections by "weight", "title", "linktitle", "modifieddate", "expirydate", "publishdate", "date", "length" or "default" (adhering to Hugo's default sort order). Default to "weight";
   # this can be overridden in the pages frontmatter
   ordersectionsby = "weight"
   # Change default color scheme with a variant one. Eg. can be "auto", "red", "blue", "green" or an array like [ "blue", "green" ].

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

@@ -28,6 +28,8 @@ This document shows you what's new in the latest release. For a detailed list of
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release adds social media meta tags for the Open Graph protocol and Twitter Cards to your site. [See the docs]({{% relref "basics/configuration#social-media-meta-tags" %}}).
 
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release comes with additional sort options for the menu and the [`children` shortcode]({{% relref "shortcodes/children" %}}). Both will now accept the following values: `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length` or `default` (adhering to Hugo's default sort order).
+
 ---
 
 ## 5.22.0 (2023-10-02) {#5220}

exampleSite/content/cont/pages/_index.en.md

@@ -69,7 +69,7 @@ collapsibleMenu = false
 # If set, this will explicitly override common rules for the expand state of a page's menu entry
 alwaysopen = true
 # If set, this will explicitly override common rules for the sorting order of a page's submenu entries
-ordersectionsby = "title"
+ordersectionsby = "weight"
 # The title of the page heading will be prefixed by this HTML content
 headingPre = ""
 # The title of the page heading will be postfixed by this HTML content

exampleSite/content/shortcodes/children/_index.en.md

@@ -41,7 +41,7 @@ While the examples are using shortcodes with named parameter you are free to als
 | **showhidden**     | `false`           | When `true`, child pages hidden from the menu will be displayed as well. |
 | **description**    | `false`           | When `true` shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - [read more info about summaries on gohugo.io](https://gohugo.io/content/summaries/). |
 | **depth**          | `1`               | The depth of descendants to display. For example, if the value is `2`, the shortcode will display two levels of child pages.  To get all descendants, set this value to a high  number eg. `999`. |
-| **sort**           | see notes         | The sort order of the displayed list.<br><br>If not set it is sorted by the [`ordersectionsby`]({{% relref "basics/configuration#global-site-parameters" %}}) setting of the site and the pages frontmatter<br><br>- `weight`: to sort on menu order<br>- `title`: to sort alphabetically on menu label. |
+| **sort**           | `auto`            | The sort criteria of the displayed list.<br><br>- `auto` defaults to [`ordersectionsby` of the pages frontmatter]({{% relref "cont/pages/#frontmatter-configuration" %}})<br>&nbsp;&nbsp;&nbsp;&nbsp;or to [`ordersectionsby` of the site configuration]({{% relref "basics/configuration#global-site-parameters" %}})<br>&nbsp;&nbsp;&nbsp;&nbsp;or to `weight`<br>- `weight`<br>- `title`<br>- `linktitle`<br>- `modifieddate`<br>- `expirydate`<br>- `publishdate`<br>- `date`<br>- `length`<br>- `default` adhering to Hugo's default sort criteria|
 
 ## Examples
 

layouts/partials/menu.html

@@ -31,17 +31,10 @@
       <div id="R-content-wrapper" class="highlightable">
         <div id="R-topics">
           <ul class="enlarge morespace collapsible-menu">
-            {{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
+            {{- $pages := partial "pageHelper/pagesBy.html" (dict "page" .Site.Home "hidden" true) }}
-            {{- $currentOrdersectionsby := .Site.Home.Params.ordersectionsby | default $defaultOrdersectionsby }}
             {{- $defaultAlwaysopen := .Site.Params.alwaysopen | default false }}
-            {{- if eq $currentOrdersectionsby "title" }}
+            {{- range $pages }}
-              {{- range .Site.Home.Pages.ByTitle }}
+              {{- template "section-tree-nav" dict "sect" . "currentnode" $currentNode "showvisitedlinks" $showvisitedlinks "alwaysopen" $defaultAlwaysopen }}
-                {{- template "section-tree-nav" dict "sect" . "currentnode" $currentNode "showvisitedlinks" $showvisitedlinks "alwaysopen" $defaultAlwaysopen }}
-              {{- end }}
-            {{- else }}
-              {{- range .Site.Home.Pages.ByWeight }}
-                {{- template "section-tree-nav" dict "sect" . "currentnode" $currentNode "showvisitedlinks" $showvisitedlinks "alwaysopen" $defaultAlwaysopen }}
-              {{- end }}
             {{- end }}
           </ul>
         </div>
@@ -151,7 +144,7 @@
         {{- $isSelf := eq .RelPermalink $currentFileRelPermalink }}
         {{- $isAncestor := and (not $isSelf) (.IsAncestor $currentNode) }}
         {{- $isActive := $isSelf }}
-        {{- $pages := .Pages }}
+        {{- $pages := partial "pageHelper/pagesBy.html" (dict "page" . "hidden" true) }}
         {{- $relearnIsHiddenFrom := index ($currentNode.Scratch.Get "relearnIsHiddenFrom") .RelPermalink }}
         {{- $hidden := and $relearnIsHiddenFrom (not $.showhidden) (not $isSelf) (not $isAncestor) }}
         {{- if $hidden }}
@@ -168,8 +161,6 @@
           {{- if $numberOfVisibleChildren }}
             {{- $title := or .Params.menuTitle .LinkTitle .Title }}
             {{- $url := partial "relLangPrettyUglyURL.hugo" (dict "to" .) }}
-            {{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
-            {{- $currentOrdersectionsby := .Params.ordersectionsby | default $defaultOrdersectionsby }}
             {{- $isCollapsible := or (.Params.collapsibleMenu | default .Site.Params.collapsibleMenu) (not $url) }}
             {{- $currentAlwaysopen := .Params.alwaysopen | default $alwaysopen }}
             {{- $pageHash := md5 .Page }}
@@ -178,14 +169,8 @@
             {{- partial "menu-pre.html" . }}{{ $title }}{{ partial "menu-post.html" . }}
             {{- if $url }}{{ if $showvisitedlinks }}<i class="fas fa-check read-icon"></i>{{ end }}</a>{{ else }}</span>{{ end }}<ul id="R-subsections-{{ $pageHash }}" class="morespace collapsible-menu">
             {{- $defaultAlwaysopen := .Site.Params.alwaysopen | default true }}
-            {{- if eq $currentOrdersectionsby "title" }}
+            {{- range $pages }}
-              {{- range $pages.ByTitle }}
+              {{- template "section-tree-nav" dict "sect" . "currentnode" $currentNode "showvisitedlinks" $showvisitedlinks "alwaysopen" $defaultAlwaysopen }}
-                {{- template "section-tree-nav" dict "sect" . "currentnode" $currentNode "showvisitedlinks" $showvisitedlinks "alwaysopen" $defaultAlwaysopen }}
-              {{- end }}
-            {{- else }}
-              {{- range $pages.ByWeight }}
-                {{- template "section-tree-nav" dict "sect" . "currentnode" $currentNode "showvisitedlinks" $showvisitedlinks "alwaysopen" $defaultAlwaysopen }}
-              {{- end }}
             {{- end }}</ul></li>
           {{- else }}
             {{- $title := or .Params.menuTitle .LinkTitle .Title }}

layouts/partials/nested-article.hugo

@@ -3,22 +3,14 @@
 {{- $page.Page.Store.Set (printf "%sIsNested" $outputFormat) true }}
 {{- with $page }}
   {{- $currentNode := . }}
-  {{- $pages := .Pages }}
+	{{- $pages := partial "pageHelper/pagesBy.html" (dict "page" . "hidden" true) }}
-  {{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
-  {{- $currentOrdersectionsby := .Params.ordersectionsby | default $defaultOrdersectionsby }}
   {{- template "section-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
   {{- if $pages }}
           <section>
             <h1 class="a11y-only">{{ T "Subsections" .Title }}</h1>
   {{- end }}
-  {{- if eq $currentOrdersectionsby "title" }}
+  {{- range $pages }}
-    {{- range $pages.ByTitle }}
+    {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
-      {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
-    {{- end }}
-  {{- else }}
-    {{- range $pages.ByWeight }}
-      {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
-    {{- end }}
   {{- end }}
   {{- if $pages }}
           </section>
@@ -31,26 +23,18 @@
   {{- with .sect }}
     {{- $isSelf := eq .RelPermalink $currentFileRelPermalink }}
     {{- $isAncestor := and (not $isSelf) (.IsAncestor $currentNode) }}
-    {{- $pages := .Pages }}
+  	{{- $pages := partial "pageHelper/pagesBy.html" (dict "page" . "hidden" true) }}
     {{- $relearnIsHiddenFrom := index ($currentNode.Scratch.Get "relearnIsHiddenFrom") .RelPermalink }}
     {{- $hidden := and $relearnIsHiddenFrom (not $.showhidden) (not $isSelf) (not $isAncestor) }}
     {{- if $hidden }}
     {{- else }}
-      {{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
-      {{- $currentOrdersectionsby := .Params.ordersectionsby | default $defaultOrdersectionsby }}
       {{- template "section-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
       {{- if $pages }}
           <section>
             <h1 class="a11y-only">{{ T "Subsections" .Title }}</h1>
       {{- end }}
-      {{- if eq $currentOrdersectionsby "title" }}
+      {{- range $pages }}
-        {{- range $pages.ByTitle }}
+        {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
-          {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
-        {{- end }}
-      {{- else }}
-        {{- range $pages.ByWeight }}
-          {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "outputFormat" $outputFormat }}
-        {{- end }}
       {{- end }}
       {{- if $pages }}
           </section>

layouts/partials/page-meta.hugo

@@ -14,14 +14,13 @@
 		{{- $currentNode.Store.Set $has true }}
 	{{- end }}
 {{- end }}
-{{- template "relearn-structure" dict "node" .Site.Home "currentnode" $currentNode "hiddenstem" false "hiddencurrent" false "defaultOrdersectionsby" (.Site.Params.ordersectionsby | default "weight") }}
+{{- template "relearn-structure" dict "node" .Site.Home "currentnode" $currentNode "hiddenstem" false "hiddencurrent" false }}
 {{- define "relearn-structure" }}
 	{{- $currentNode := .currentnode }}
 	{{- $isSelf := eq $currentNode .node }}
 	{{- $isDescendant := and (not $isSelf) (.node.IsDescendant $currentNode) }}
 	{{- $isAncestor := and (not $isSelf) (.node.IsAncestor $currentNode) }}
 	{{- $isOther := and (not $isDescendant) (not $isSelf) (not $isAncestor) }}
-
 	{{- $isChildren := eq $currentNode .node.Parent }}
 	{{- if $isSelf }}
 		{{- $currentNode.Scratch.Set "relearnIsSelfFound" true }}
@@ -48,15 +47,8 @@
 		{{- end}}
 	{{- end }}
 
-	{{- $pages := .node.Pages }}
+	{{- $pages := partial "pageHelper/pagesBy.html" (dict "page" .node "hidden" true) }}
-	{{- $defaultOrdersectionsby := .defaultOrdersectionsby }}
-	{{- $currentOrdersectionsby := .node.Params.ordersectionsby | default $defaultOrdersectionsby }}
-	{{- if eq $currentOrdersectionsby "title"}}
-		{{- $pages = $pages.ByTitle }}
-	{{- else}}
-		{{- $pages = $pages.ByWeight }}
-	{{- end }}
 	{{- range $pages }}
-		{{- template "relearn-structure" dict "node" . "currentnode" $currentNode "hiddenstem" $hidden_stem "hiddencurrent" $hidden_from_current "defaultOrdersectionsby" $defaultOrdersectionsby }}
+		{{- template "relearn-structure" dict "node" . "currentnode" $currentNode "hiddenstem" $hidden_stem "hiddencurrent" $hidden_from_current }}
 	{{- end}}
 {{- end }}

layouts/partials/pageHelper/isHidden.html

@@ -0,0 +1 @@
+{{- return (or (not .Title) .Params.hidden) }}

layouts/partials/pageHelper/pagesBy.html

@@ -0,0 +1,45 @@
+{{- $page := .page }}
+{{- /* default sort order for the theme is historically by weight */}}
+{{- $by := .by }}
+{{- if eq $by "auto" }}
+	{{- $by = "" }}
+{{- end }}
+{{- $by = $by | default $page.Params.ordersectionsby | default $page.Site.Params.ordersectionsby | default "weight" }}
+{{- $hidden := .hidden }}
+
+{{- $pages := slice }}
+
+{{- if eq $by "weight" }}
+	{{- $pages = $page.Pages.ByWeight }}
+{{- else if or (eq $by "name") (eq $by "title") }}
+	{{- $pages = $page.Pages.ByTitle }}
+{{- else if eq $by "linktitle" }}
+	{{- $pages = $page.Pages.ByLinkTitle }}
+{{- else if eq $by "modifieddate" }}
+	{{- $pages = $page.Pages.Lastmod }}
+{{- else if eq $by "expirydate" }}
+	{{- $pages = $page.Pages.ByExpiryDate }}
+{{- else if eq $by "publishdate" }}
+	{{- $pages = $page.Pages.ByPublishDate }}
+{{- else if eq $by "date" }}
+	{{- $pages = $page.Pages.ByDate }}
+{{- else if eq $by "length" }}
+	{{- $pages = $page.Pages.ByLength }}
+{{- else if eq $by "default" }}
+	{{- $pages = $page.Pages }}
+{{- else }}
+	{{- warnf "%q: Unknown pages sort order '%s'" $page.File.Path }}
+	{{- $pages = $page.Pages }}
+{{- end }}
+
+{{- if not $hidden }}
+	{{- $nonhiddenpages := slice }}
+	{{- range $page := $pages }}
+		{{- if not (partial "pageHelper/isHidden.html" $page) }}
+			{{- $nonhiddenpages := $nonhiddenpages | append $page }}
+		{{- end }}
+	{{- end }}
+	{{- $pages = $nonhiddenpages }}
+{{- end }}
+
+{{- return $pages }}

layouts/partials/shortcodes/children.html

@@ -21,23 +21,8 @@
 
 {{- with $page }}
 {{ (printf "<%s class=\"children children-%s children-sort-%s\">" $containerstyle $style $sortTerm)|safeHTML }}
-	{{- $pages := .Pages }}
+	{{- $pages := partial "pageHelper/pagesBy.html" (dict "page" . "hidden" true) }}
-
+	{{- template "childs" dict "menu" $pages "containerstyle" $containerstyle "style" $style "showhidden" $showhidden "count" 1 "depth" $depth "pages" .Site.Pages "description" $withDescription "sortTerm" $sortTerm "page" . }}
-	{{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
-	{{- $currentOrdersectionsby := $sortTerm | default (.Params.ordersectionsby | default $defaultOrdersectionsby) }}
-	{{- if eq $currentOrdersectionsby "weight" }}
-		{{- template "childs" dict "menu" $pages.ByWeight "containerstyle" $containerstyle "style" $style "showhidden" $showhidden "count" 1 "depth" $depth "pages" .Site.Pages "description" $withDescription "sortTerm" $sortTerm "page" . }}
-	{{- else if or (eq $currentOrdersectionsby "name") (eq $currentOrdersectionsby "title") }}
-		{{- template "childs" dict "menu" $pages.ByTitle "containerstyle" $containerstyle "style" $style "showhidden" $showhidden "count" 1 "depth" $depth "pages" .Site.Pages "description" $withDescription "sortTerm" $sortTerm "page" . }}
-	{{- else if eq $currentOrdersectionsby "publishdate" }}
-		{{- template "childs" dict "menu" $pages.ByPublishDate "containerstyle" $containerstyle "style" $style "showhidden" $showhidden "count" 1 "depth" $depth "pages" .Site.Pages "description" $withDescription "sortTerm" $sortTerm "page" . }}
-	{{- else if eq $currentOrdersectionsby "date" }}
-		{{- template "childs" dict "menu" $pages.ByDate "containerstyle" $containerstyle "style" $style "showhidden" $showhidden "count" 1 "depth" $depth "pages" .Site.Pages "description" $withDescription "sortTerm" $sortTerm "page" . }}
-	{{- else if eq $currentOrdersectionsby "length" }}
-		{{- template "childs" dict "menu" $pages.ByLength "containerstyle" $containerstyle "style" $style "showhidden" $showhidden "count" 1 "depth" $depth "pages" .Site.Pages "description" $withDescription "sortTerm" $sortTerm "page" . }}
-	{{- else }}
-		{{- template "childs" dict "menu" $pages "containerstyle" $containerstyle "style" $style "showhidden" $showhidden "count" 1 "depth" $depth "pages" .Site.Pages "description" $withDescription "sortTerm" $sortTerm "page" . }}
-	{{- end }}
 {{ (printf "</%s>" $containerstyle)|safeHTML }}
 {{- end }}
 
@@ -87,23 +72,8 @@
 {{- (printf "<%s>" $.containerstyle)|safeHTML }}
 				{{- end }}
 
-				{{- $pages := .Pages }}
+				{{- $pages := partial "pageHelper/pagesBy.html" (dict "page" . "hidden" true) }}
-
+				{{- template "childs" dict "menu" $pages "containerstyle" $.containerstyle "style" $.style "showhidden" $.showhidden "count" (add $.count 1) "depth" $.depth "pages" $.pages "description" $.description "sortTerm" $.sortTerm "page" $page }}
-				{{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
-				{{- $currentOrdersectionsby := $.sortTerm | default (.Params.ordersectionsby | default $defaultOrdersectionsby) }}
-				{{- if eq $currentOrdersectionsby "weight" }}
-					{{- template "childs" dict "menu" $pages.ByWeight "containerstyle" $.containerstyle "style" $.style "showhidden" $.showhidden "count" (add $.count 1) "depth" $.depth "pages" $.pages "description" $.description "sortTerm" $.sortTerm "page" $page }}
-				{{- else if or (eq $.currentOrdersectionsby "name") (eq $.currentOrdersectionsby "title") }}
-					{{- template "childs" dict "menu" $pages.ByTitle "containerstyle" $.containerstyle "style" $.style "showhidden" $.showhidden "count" (add $.count 1) "depth" $.depth "pages" $.pages "description" $.description "sortTerm" $.sortTerm "page" $page }}
-				{{- else if eq $.currentOrdersectionsby "publishdate" }}
-					{{- template "childs" dict "menu" $pages.ByPublishDate "containerstyle" $.containerstyle "style" $.style "showhidden" $.showhidden "count" (add $.count 1) "depth" $.depth "pages" $.pages "description" $.description "sortTerm" $.sortTerm "page" $page }}
-				{{- else if eq $.currentOrdersectionsby "date" }}
-					{{- template "childs" dict "menu" $pages.ByDate "containerstyle" $.containerstyle "style" $.style "showhidden" $.showhidden "count" (add $.count 1) "depth" $.depth "pages" $.pages "description" $.description "sortTerm" $.sortTerm "page" $page }}
-				{{- else if eq $.currentOrdersectionsby "length" }}
-					{{- template "childs" dict "menu" $pages.ByLength "containerstyle" $.containerstyle "style" $.style "showhidden" $.showhidden "count" (add $.count 1) "depth" $.depth "pages" $.pages "description" $.description "sortTerm" $.sortTerm "page" $page }}
-				{{- else }}
-					{{- template "childs" dict "menu" $pages "containerstyle" $.containerstyle "style" $.style "showhidden" $.showhidden "count" (add $.count 1) "depth" $.depth "pages" $.pages "description" $.description "sortTerm" $.sortTerm "page" $page }}
-				{{- end }}
 
 				{{- if eq $.style "li" }}
 {{- (printf "</%s>" $.containerstyle)|safeHTML }}