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 <[email protected]>

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.

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 -}}