From bbffff1f52aeb21ba598c456d49a234318b270fc Mon Sep 17 00:00:00 2001
From: Keith Stockdale <kstocky1@gmail.com>
Date: Tue, 26 Aug 2025 20:46:51 +0100
Subject: [PATCH] feat: support breadcrumbs for single pages that are neither
 docs or blogs (#743)

* feat: support breadcrumbs for single pages that are neither docs or blogs.

* feat: support enabling breadcrumbs across different content types other than docs and blog

docs: added docs and examples for enabling breadcrumbs for specific content types

* feat: breadcrumbs being enabled is fully driven by the `breadcrumbs` front matter field.

docs: updated docs to reflect that there is no site parameter driving breadcrumbs

feat: enabled breadcrumbs for lists as well as singles for uniformity

* Removing _partials/utils/default-breadcrumbs-enabled.html in favour of extra parameterization of _partials/breadcrumb.html

* fix: change breadcrumbs parameter from `enabledByDefault` to `enable` to remain consistent with the rest of the theme

* Update layouts/_partials/breadcrumb.html

---------

Co-authored-by: Xin <5097752+imfing@users.noreply.github.com>
---
 .../content/docs/guide/organize-files.md      | 24 +++++++++++++++++--
 layouts/_partials/breadcrumb.html             |  8 ++++---
 layouts/blog/list.html                        |  1 +
 layouts/blog/single.html                      |  2 +-
 layouts/docs/list.html                        |  2 +-
 layouts/docs/single.html                      |  2 +-
 layouts/list.html                             |  1 +
 layouts/single.html                           |  1 +
 8 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/exampleSite/content/docs/guide/organize-files.md b/exampleSite/content/docs/guide/organize-files.md
index cef0e51..e26b00d 100644
--- a/exampleSite/content/docs/guide/organize-files.md
+++ b/exampleSite/content/docs/guide/organize-files.md
@@ -180,9 +180,17 @@ This would now generate the following breadcrumbs:
 Documentation > Guide > Foo Bar
 ```
 
-### Hiding Breadcrumbs
+### Enabling and Disabling Breadcrumbs
 
-You can hide breadcrumbs completely from a page by specifying `breadcrumbs: false` in its front matter:
+Whether breadcrumbs are enabled, or disabled, by default for a page, is determined by its [content type](https://gohugo.io/quick-reference/glossary/#content-type) and [page kind](https://gohugo.io/quick-reference/glossary/#page-kind):
+
+|  Content Type   | Section  | Page      |
+|:----------------|:--------:|:----------|
+| `docs`          | Enabled  | Enabled   |
+| `blog`          | Disabled | Enabled   |
+| Any other type  | Disabled | Disabled  |
+
+You can override these defaults on a page by setting `breadcrumbs` in its front matter:
 
 ```yaml {filename="content/docs/guide/organize-files.md"}
 ---
@@ -191,6 +199,18 @@ title: Organize Files
 ---
 ```
 
+Similarly you can use [cascade](https://gohugo.io/content-management/front-matter/#cascade-1) to override the defaults on a page and its decendents:
+
+```yaml {filename="content/portfolio/_index.md"}
+---
+title: "Portfolio"
+
+cascade:
+  params:
+    breadcrumbs: true
+---
+```
+
 ## Configure Content Directory
 
 By default, the root `content/` directory is used by Hugo to build the site.
diff --git a/layouts/_partials/breadcrumb.html b/layouts/_partials/breadcrumb.html
index 7dcc209..27be23d 100644
--- a/layouts/_partials/breadcrumb.html
+++ b/layouts/_partials/breadcrumb.html
@@ -1,6 +1,8 @@
-{{- if (default true .Params.breadcrumbs) }}
+{{- $page := .page -}}
+{{- $enable := .enable -}}
+{{- if (default $enable $page.Params.breadcrumbs) -}}
   <div class="hx:mt-1.5 hx:flex hx:items-center hx:gap-1 hx:overflow-hidden hx:text-sm hx:text-gray-500 hx:dark:text-gray-400 hx:contrast-more:text-current">
-    {{- range .Ancestors.Reverse }}
+    {{- range $page.Ancestors.Reverse }}
       {{- if not .IsHome }}
         <div class="hx:whitespace-nowrap hx:transition-colors hx:min-w-[24px] hx:overflow-hidden hx:text-ellipsis hx:hover:text-gray-900 hx:dark:hover:text-gray-100">
           <a href="{{ .RelPermalink }}">{{- partial "utils/title" . -}}</a>
@@ -9,7 +11,7 @@
       {{ end -}}
     {{ end -}}
     <div class="hx:whitespace-nowrap hx:transition-colors hx:font-medium hx:text-gray-700 hx:contrast-more:font-bold hx:contrast-more:text-current hx:dark:text-gray-100 hx:contrast-more:dark:text-current">
-      {{- partial "utils/title" . -}}
+      {{- partial "utils/title" $page -}}
     </div>
   </div>
 {{ end -}}
diff --git a/layouts/blog/list.html b/layouts/blog/list.html
index f86061b..da04445 100644
--- a/layouts/blog/list.html
+++ b/layouts/blog/list.html
@@ -4,6 +4,7 @@
     {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" true) }}
     <article class="hx:w-full hx:break-words hx:flex hx:min-h-[calc(100vh-var(--navbar-height))] hx:min-w-0 hx:justify-center hx:pb-8 hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="hx:w-full hx:min-w-0 hx:max-w-6xl hx:px-6 hx:pt-4 hx:md:px-12">
+        {{ partial "breadcrumb.html" (dict "page" . "enable" false) }}
         <br class="hx:mt-1.5 hx:text-sm" />
         {{ if .Title }}<h1 class="hx:text-center hx:mt-2 hx:text-4xl hx:font-bold hx:tracking-tight hx:text-slate-900 hx:dark:text-slate-100">{{ .Title }}</h1>{{ end }}
         <div class="content">{{ .Content }}</div>
diff --git a/layouts/blog/single.html b/layouts/blog/single.html
index 66222ed..7a5b870 100644
--- a/layouts/blog/single.html
+++ b/layouts/blog/single.html
@@ -4,7 +4,7 @@
     {{ partial "toc.html" . }}
     <article class="hx:w-full hx:break-words hx:flex hx:min-h-[calc(100vh-var(--navbar-height))] hx:min-w-0 hx:justify-center hx:pb-8 hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="hx:w-full hx:min-w-0 hx:max-w-6xl hx:px-6 hx:pt-4 hx:md:px-12">
-        {{ partial "breadcrumb.html" . }}
+        {{ partial "breadcrumb.html" (dict "page" . "enable" true) }}
         {{ if .Title }}<h1 class="hx:mt-2 hx:text-4xl hx:font-bold hx:tracking-tight hx:text-slate-900 hx:dark:text-slate-100">{{ .Title }}</h1>{{ end }}
         <div class="hx:mt-4 hx:mb-16 hx:text-gray-500 hx:dark:text-gray-400 hx:text-sm hx:flex hx:items-center hx:flex-wrap hx:gap-y-2">
           {{- with $date := .Date }}<span class="hx:mr-1">{{ partial "utils/format-date" $date }}</span>{{ end -}}
diff --git a/layouts/docs/list.html b/layouts/docs/list.html
index 3c80126..a8795cb 100644
--- a/layouts/docs/list.html
+++ b/layouts/docs/list.html
@@ -4,7 +4,7 @@
     {{ partial "toc.html" . }}
     <article class="hx:w-full hx:break-words hx:flex hx:min-h-[calc(100vh-var(--navbar-height))] hx:min-w-0 hx:justify-center hx:pb-8 hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="hx:w-full hx:min-w-0 hx:max-w-6xl hx:px-6 hx:pt-4 hx:md:px-12">
-        {{ partial "breadcrumb.html" . }}
+        {{ partial "breadcrumb.html" (dict "page" . "enable" true) }}
         <div class="content">
           {{ if .Title }}<h1>{{ .Title }}</h1>{{ end }}
           {{ .Content }}
diff --git a/layouts/docs/single.html b/layouts/docs/single.html
index 3c80126..a8795cb 100644
--- a/layouts/docs/single.html
+++ b/layouts/docs/single.html
@@ -4,7 +4,7 @@
     {{ partial "toc.html" . }}
     <article class="hx:w-full hx:break-words hx:flex hx:min-h-[calc(100vh-var(--navbar-height))] hx:min-w-0 hx:justify-center hx:pb-8 hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="hx:w-full hx:min-w-0 hx:max-w-6xl hx:px-6 hx:pt-4 hx:md:px-12">
-        {{ partial "breadcrumb.html" . }}
+        {{ partial "breadcrumb.html" (dict "page" . "enable" true) }}
         <div class="content">
           {{ if .Title }}<h1>{{ .Title }}</h1>{{ end }}
           {{ .Content }}
diff --git a/layouts/list.html b/layouts/list.html
index 653f6f1..55e7825 100644
--- a/layouts/list.html
+++ b/layouts/list.html
@@ -4,6 +4,7 @@
     {{ partial "toc.html" . }}
     <article class="hx:w-full hx:break-words hx:flex hx:min-h-[calc(100vh-var(--navbar-height))] hx:min-w-0 hx:justify-center hx:pb-8 hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="hx:w-full hx:min-w-0 hx:max-w-6xl hx:px-6 hx:pt-4 hx:md:px-12">
+        {{ partial "breadcrumb.html" (dict "page" . "enable" false) }}
         <div class="content">
           {{ if .Title }}<h1>{{ .Title }}</h1>{{ end }}
           {{ .Content }}
diff --git a/layouts/single.html b/layouts/single.html
index fe9f338..a9e8ac5 100644
--- a/layouts/single.html
+++ b/layouts/single.html
@@ -4,6 +4,7 @@
     {{ partial "toc.html" . }}
     <article class="hx:w-full hx:break-words hx:flex hx:min-h-[calc(100vh-var(--navbar-height))] hx:min-w-0 hx:justify-center hx:pb-8 hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="hx:w-full hx:min-w-0 hx:max-w-6xl hx:px-6 hx:pt-4 hx:md:px-12">
+        {{ partial "breadcrumb.html" (dict "page" . "enable" false) }}
         <br class="hx:mt-1.5 hx:text-sm" />
         {{ if .Title }}<h1 class="hx:text-center hx:mt-2 hx:text-4xl hx:font-bold hx:tracking-tight hx:text-slate-900 hx:dark:text-slate-100">{{ .Title }}</h1>{{ end }}
         <div class="hx:mb-16"></div>