From 3cba6b9820221cd212fdb455a2581a3c7d5c3395 Mon Sep 17 00:00:00 2001
From: George Gecewicz <875201+ggwicz@users.noreply.github.com>
Date: Sun, 2 Jun 2024 06:01:06 -0400
Subject: [PATCH] feat: add support for `breadcrumbs` param in front matter for
 showing/hiding breadcrumbs on specific pages (#367)

* feat: add support for `hideBreadcrumbs` front-matter param

* docs(en): add some docs about breadcrumb nav, including new hideBreadcrumbs param

* fix: fix typo in hideBreadcrumbs param check in breadcrumbs.html partial

* docs(en): tidy up the Breadcrumb Navigation documentation

* fix: rework hideBreadcrumbs param to breadcrumbs; update docs accordingly

* fix: use relpermalink in breadcrumb

---------

Co-authored-by: Xin <xin@imfing.com>
---
 .../content/docs/guide/organize-files.md      | 39 +++++++++++++++++++
 layouts/partials/breadcrumb.html              | 24 ++++++------
 2 files changed, 52 insertions(+), 11 deletions(-)

diff --git a/exampleSite/content/docs/guide/organize-files.md b/exampleSite/content/docs/guide/organize-files.md
index 8c343abc..e3a69662 100644
--- a/exampleSite/content/docs/guide/organize-files.md
+++ b/exampleSite/content/docs/guide/organize-files.md
@@ -82,6 +82,45 @@ weight: 2
   It is recommended to keep the sidebar not too deep. If you have a lot of content, consider **splitting them into multiple sections**.
 {{< /callout >}}
 
+## Breadcrumb Navigation
+
+Breadcrumbs are auto-generated based on the directory structure of `/content`.
+
+For example, consider the file structure [demonstrated above](#directory-structure). Given that structure, the breadcrumbs atop the page at `/docs/guide/organize-files/` would appear automatically as follows:
+
+```
+Documentation > Guide > Organize Files
+```
+
+### Customizing Breadcrumb Link Titles
+
+By default, each breadcrumb link is generated based on that page's `title` parameter. You can customize this by specifying a `linkTitle`.
+
+For example, if instead of `Organize Files` we wanted the breadcrumb to be `Foo Bar`:
+
+```yaml {filename="content/docs/guide/organize-files.md"}
+---
+linkTitle: Foo Bar
+title: Organize Files
+---
+```
+
+This would now generate the following breadcrumbs:
+```
+Documentation > Guide > Foo Bar
+```
+
+### Hiding Breadcrumbs
+
+You can hide breadcrumbs completely from a page by specfying `breadcrumbs: false` in its front matter:
+
+```yaml {filename="content/docs/guide/organize-files.md"}
+---
+breadcrumbs: false
+title: Organize Files
+---
+```
+
 ## 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 f3852754..fa52f9b9 100644
--- a/layouts/partials/breadcrumb.html
+++ b/layouts/partials/breadcrumb.html
@@ -1,13 +1,15 @@
-<div class="hx-mt-1.5 hx-flex hx-items-center hx-gap-1 hx-overflow-hidden hx-text-sm hx-text-gray-500 dark:hx-text-gray-400 contrast-more:hx-text-current">
-  {{- range .Ancestors.Reverse }}
-    {{- if not .IsHome }}
-      <div class="hx-whitespace-nowrap hx-transition-colors hx-min-w-[24px] hx-overflow-hidden hx-text-ellipsis hover:hx-text-gray-900 dark:hover:hx-text-gray-100">
-        <a href="{{ .Permalink }}">{{- partial "utils/title" . -}}</a>
-      </div>
-      {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx-w-3.5 hx-shrink-0 rtl:-hx-rotate-180\"") -}}
+{{- if (default true .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 dark:hx-text-gray-400 contrast-more:hx-text-current">
+    {{- range .Ancestors.Reverse }}
+      {{- if not .IsHome }}
+        <div class="hx-whitespace-nowrap hx-transition-colors hx-min-w-[24px] hx-overflow-hidden hx-text-ellipsis hover:hx-text-gray-900 dark:hover:hx-text-gray-100">
+          <a href="{{ .RelPermalink }}">{{- partial "utils/title" . -}}</a>
+        </div>
+        {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx-w-3.5 hx-shrink-0 rtl:-hx-rotate-180\"") -}}
+      {{ end -}}
     {{ end -}}
-  {{ end -}}
-  <div class="hx-whitespace-nowrap hx-transition-colors hx-font-medium hx-text-gray-700 contrast-more:hx-font-bold contrast-more:hx-text-current dark:hx-text-gray-100 contrast-more:dark:hx-text-current">
-    {{- partial "utils/title" . -}}
+    <div class="hx-whitespace-nowrap hx-transition-colors hx-font-medium hx-text-gray-700 contrast-more:hx-font-bold contrast-more:hx-text-current dark:hx-text-gray-100 contrast-more:dark:hx-text-current">
+      {{- partial "utils/title" . -}}
+    </div>
   </div>
-</div>
+{{ end -}}