Adds a warning when truncating sidebar section entries (#2069)

Author: chalin

CHANGELOG.md

@@ -32,13 +32,17 @@ For the full list of changes, see the [0.x.y] release notes.
   base support for RTL][bs-rtl].
 - The URL to your project's contribution guidelines is configurable. For
   details, see [Adding a community page].
+- A warning is now output when a section's sidebar entries are truncated because
+  there are more than [params.ui.sidebar_menu_truncate] section entries.
 
 **Other changes**: TBC
 
 [0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y
 [bs-rtl]: https://getbootstrap.com/docs/5.3/getting-started/rtl/
 [Adding a community page]:
   https://www.docsy.dev/docs/adding-content/content/#adding-a-community-page
+[params.ui.sidebar_menu_truncate]:
+  https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options
 
 ## 0.10.0
 

layouts/partials/sidebar-tree.html

@@ -30,7 +30,7 @@
     {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection -}}
     {{ $ulNr := 0 -}}
     {{ $ulShow := .Site.Params.ui.ul_show | default 1 -}}
-    {{ $sidebarMenuTruncate := .Site.Params.ui.sidebar_menu_truncate | default 50 -}}
+    {{ $sidebarMenuTruncate := .Site.Params.ui.sidebar_menu_truncate | default 100 -}}
     <ul class="td-sidebar-nav__section pe-md-3 ul-{{ $ulNr }}">
       {{ template "section-tree-nav-section" (dict "page" . "section" $navRoot "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" (add $ulShow 1)) }}
     </ul>
@@ -50,6 +50,11 @@
 {{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}}
 {{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}}
 {{ $pages := $pages_tmp | first $sidebarMenuTruncate -}}
+{{ $truncatedEntryCount := sub (len $pages_tmp) $sidebarMenuTruncate -}}
+{{ if gt $truncatedEntryCount 0 -}}
+  {{ warnf "WARNING: %d sidebar entries have been truncated. To avoid this, increase `params.ui.sidebar_menu_truncate` to at least %d (from %d) in your config file. Section: %s"
+      $truncatedEntryCount (len $pages_tmp) $sidebarMenuTruncate  $s.Path -}}
+{{ end -}}
 {{ $withChild := gt (len $pages) 0 -}}
 {{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}}
 {{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}}
@@ -71,4 +76,4 @@
   </ul>
   {{- end }}
 </li>
-{{- end }}
+{{- end -}}

userguide/content/en/docs/adding-content/navigation.md

@@ -222,7 +222,7 @@ By default, the section menu shows the current section fully expanded all the wa
 
 With the compact menu (`.ui.sidebar_menu_compact = true`), only the current page's ancestors, siblings and direct descendants are shown. You can use the optional parameter `.ui.ul_show` to set a desired menu depth to always be visible. For example, with `.ui.ul_show = 1` the first menu level is always displayed.
 
-The number of sidebar entries shown per section can be configured using the `.ui.sidebar_menu_truncate` parameter (default: 50).
+The number of sidebar entries shown per section can be configured using the `.ui.sidebar_menu_truncate` parameter (default: 100).
 
 As well as the completely expanded and compact menu options, you can also create a foldable menu by setting the site parameter `ui.sidebar_menu_foldable = true` in `hugo.toml`. The foldable menu lets users expand and collapse menu sections by toggling arrow icons beside the section parents in the menu.