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>

.github/CONTRIBUTING.md

@@ -57,7 +57,7 @@ We recommend that you search existing [issues][issues] or discussions before ope
 
 ### Local development setup
 
-- [Hugo][hugo] >= v0.115.0 (extended version)
+- [Hugo][hugo] >= v0.124.0 (extended version)
 - [Node.js][nodejs]
 - [Go][go]
 

.github/workflows/pages.yml

@@ -31,7 +31,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      HUGO_VERSION: 0.124.1
+      HUGO_VERSION: 0.126.1
     steps:
       - name: Checkout
         uses: actions/checkout@v4

exampleSite/content/docs/guide/markdown.md

@@ -14,7 +14,7 @@ Hugo supports [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax for form
 | Style   | Syntax     | Example   | Output   |
 | --------  | -------- | ------ | ------ |
 | Bold | `**bold text**` | `**bold text**` | **bold text** |
-| Italic | `*italicized text*` | `*italicized text* | *italicized text* |
+| Italic | `*italicized text*` | `*italicized text*` | *italicized text* |
 | Strikethrough | `~~strikethrough text~~` | `~~strikethrough text~~` | ~~strikethrough text~~ |
 | Subscript | `<sub></sub>` | `This is a <sub>subscript</sub> text` | This is a <sub>subscript</sub> text |
 | Superscript | `<sup></sup>` | `This is a <sup>superscript</sup> text` | This is a <sup>superscript</sup> text |

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.

exampleSite/content/showcase/index.md

@@ -13,6 +13,13 @@ Open source projects powered by Hextra
 
 {{< cards >}}
 
+  {{< card
+        link="https://github.com/axivo/website"
+        title="AXIVO Docs"
+        image="https://github.com/imfing/hextra/assets/19806136/f22f0710-23a0-430b-8bad-616283b8a3e5"
+        imageStyle="object-fit:cover; aspect-ratio:16/9;"
+  >}}
+
   {{< card
         link="https://github.com/infracourse/web"
         title="Stanford CS 40"

exampleSite/content/showcase/index.zh-cn.md

@@ -13,6 +13,13 @@ layout: wide
 
 {{< cards >}}
 
+  {{< card
+        link="https://github.com/axivo/website"
+        title="AXIVO Docs"
+        image="https://github.com/imfing/hextra/assets/19806136/f22f0710-23a0-430b-8bad-616283b8a3e5"
+        imageStyle="object-fit:cover; aspect-ratio:16/9;"
+  >}}
+
   {{< card
         link="https://github.com/infracourse/web"
         title="Stanford CS 40"

i18n/he.yaml

@@ -0,0 +1,14 @@
+backToTop: "גלול למעלה"
+changeLanguage: "שנה שפה"
+changeTheme: "שנה ערכת צבעים"
+copyCode: "העתק קוד"
+copyright: "© 2024 פרוייקט Hextra"
+dark: "כהה"
+editThisPage: "← ערוך עמוד זה בגיטהאב"
+lastUpdated: "עודכן לאחרונה ב"
+light: "בהיר"
+noResultsFound: "לא נמצאו תוצאות."
+onThisPage: "בעמוד זה"
+poweredBy: "Hextra מופעל על-ידי"
+readMore: "← קרא עוד"
+searchPlaceholder: "חיפוש..."

i18n/nl.yaml

@@ -0,0 +1,14 @@
+backToTop: "Terug naar boven"
+changeLanguage: "Taal veranderen"
+changeTheme: "Thema aanpassen"
+copyCode: "Kopieer code"
+copyright: "© 2024 Hextra Project."
+dark: "Donker"
+editThisPage: "Bewerk deze pagina op GitHub →"
+lastUpdated: "Laatst bijgewerkt op"
+light: "Licht"
+noResultsFound: "Geen resultaten gevonden."
+onThisPage: "Op deze pagina"
+poweredBy: "Mogelijk gemaakt door Hextra"
+readMore: "Lees meer →"
+searchPlaceholder: "Zoeken..."

i18n/uk.yaml

@@ -0,0 +1,14 @@
+backToTop: "Прокрутити до початку"
+changeLanguage: "Змінити мову"
+changeTheme: "Змінити тему"
+copyCode: "Скопіювати код"
+copyright: "2024 Проєкт Hextra."
+dark: "Темна"
+editThisPage: "Редагувати цю сторінку на Github →"
+lastUpdated: "Востаннє оновлено"
+light: "Світла"
+noResultsFound: "Не знайдено результатів"
+onThisPage: "На цій сторінці"
+poweredBy: "Працює завдяки Hextra"
+readMore: "Читати більше →"
+searchPlaceholder: "Пошук..."

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

layouts/partials/footer.html

@@ -20,7 +20,7 @@
       {{- partial "language-switch.html" (dict "context" .) -}}
       {{- with $displayThemeToggle }}{{ partial "theme-toggle.html" }}{{ end -}}
     </div>
-    {{- if or site.IsMultiLingual $displayThemeToggle -}}
+    {{- if or hugo.IsMultilingual $displayThemeToggle -}}
       <hr class="dark:hx-border-neutral-800" />
     {{- end -}}
   {{- end -}}

layouts/partials/language-switch.html

@@ -5,7 +5,7 @@
 
 {{- $changeLanguage := (T "changeLanguage") | default "Change language" -}}
 
-{{- if site.IsMultiLingual -}}
+{{- if hugo.IsMultilingual -}}
   <div class="hx-flex hx-justify-items-start {{ if $grow }}hx-grow{{ end }}">
     <button
       title="{{ $changeLanguage }}"

layouts/partials/sidebar.html

@@ -43,9 +43,9 @@
   {{ $switchesClass := cond $disableSidebar "md:hx-hidden" "" -}}
   {{ $displayThemeToggle := (site.Params.theme.displayToggle | default true) -}}
 
-  {{ if or site.IsMultiLingual $displayThemeToggle }}
-    <div class="{{ $switchesClass }} {{ with site.IsMultiLingual }}hx-justify-end{{ end }} hx-sticky hx-bottom-0 hx-bg-white dark:hx-bg-dark hx-mx-4 hx-py-4 hx-shadow-[0_-12px_16px_#fff] hx-flex hx-items-center hx-gap-2 dark:hx-border-neutral-800 dark:hx-shadow-[0_-12px_16px_#111] contrast-more:hx-border-neutral-400 contrast-more:hx-shadow-none contrast-more:dark:hx-shadow-none hx-border-t" data-toggle-animation="show">
-      {{- with site.IsMultiLingual -}}
+  {{ if or hugo.IsMultilingual $displayThemeToggle }}
+    <div class="{{ $switchesClass }} {{ with hugo.IsMultilingual }}hx-justify-end{{ end }} hx-sticky hx-bottom-0 hx-bg-white dark:hx-bg-dark hx-mx-4 hx-py-4 hx-shadow-[0_-12px_16px_#fff] hx-flex hx-items-center hx-gap-2 dark:hx-border-neutral-800 dark:hx-shadow-[0_-12px_16px_#111] contrast-more:hx-border-neutral-400 contrast-more:hx-shadow-none contrast-more:dark:hx-shadow-none hx-border-t" data-toggle-animation="show">
+      {{- with hugo.IsMultilingual -}}
         {{- partial "language-switch" (dict "context" $context "grow" true) -}}
         {{- with $displayThemeToggle }}{{ partial "theme-toggle" (dict "hideLabel" true) }}{{ end -}}
       {{- else -}}

layouts/shortcodes/hextra/hero-container.html

@@ -0,0 +1,38 @@
+{{- $class := .Get "class" -}}
+{{- $cols := .Get "cols" | default 2 -}}
+{{- $image := .Get "image" -}}
+{{- $imageCard := .Get "imageCard" | default false -}}
+{{- $imageClass := .Get "imageClass" -}}
+{{- $imageLink := .Get "imageLink" -}}
+{{- $imageLinkExternal := hasPrefix $imageLink "http" -}}
+{{- $imageStyle := .Get "imageStyle" -}}
+{{- $imageTitle := .Get "imageTitle" -}}
+{{- $imageWidth := .Get "imageWidth" | default 350 -}}
+{{- $imageHeight := .Get "imageHeight" | default 350 -}}
+{{- $style := .Get "style" -}}
+
+{{- $css := printf "--hextra-feature-grid-cols: %v; %s" $cols $style -}}
+{{- $href := cond (hasPrefix $imageLink "/") ($imageLink | relURL) $imageLink -}}
+{{- if hasPrefix $image "/" -}}
+  {{- $image = relURL (strings.TrimPrefix "/" $image) -}}
+{{- end -}}
+
+<div
+  class="{{ $class }} hextra-feature-grid hx-grid sm:max-lg:hx-grid-cols-2 max-sm:hx-grid-cols-1 hx-gap-4 hx-w-full not-prose"
+  {{ with $css }}style="{{ . | safeCSS }}"{{ end }}
+>
+  <div class="hx-w-full">
+    {{ .Inner }}
+  </div>
+  {{- with $image }}
+  <div class="hx-mx-auto">
+    <a
+      {{ with $imageLink }}href="{{ $href }}" {{ with $imageLinkExternal }} target="_blank" rel="noreferrer"{{ end }}{{ end }}
+      {{ with $imageStyle }}style="{{ . | safeCSS }}"{{ end }}
+      class="{{ $imageClass }} {{ if $imageCard }}hextra-feature-card not-prose hx-block hx-relative hx-p-6 hx-overflow-hidden hx-rounded-3xl hx-border hx-border-gray-200 hover:hx-border-gray-300 dark:hx-border-neutral-800 dark:hover:hx-border-neutral-700 before:hx-pointer-events-none before:hx-absolute before:hx-inset-0 before:hx-bg-glass-gradient{{ end }}"
+    >
+      <img src="{{ $image }}" width="{{ $imageWidth }}" height="{{ $imageHeight }}" {{ with $imageTitle }}alt="{{ $imageTitle }}"{{ end }}/>
+    </a>
+  </div>
+  {{ end -}}
+</div>

netlify.toml

@@ -7,4 +7,6 @@ command = "cd exampleSite && hugo --gc --minify --themesDir ../.. -b ${DEPLOY_PR
 ignore = "false"
 
 [build.environment]
-HUGO_VERSION = "0.117.0"
+HUGO_VERSION = "0.126.1"
+GO_VERSION = "1.22.3"
+NODE_VERSION = "22.2.0"

theme.toml

@@ -9,7 +9,7 @@ homepage = "https://github.com/imfing/hextra/"
 demosite = "https://imfing.github.io/hextra/"
 tags = ["Modern", "Elegant", "Blog", "Documentation", "Responsive", "Clean", "Light", "Dark", "Minimal"]
 features = ["Responsive", "Dark Mode", "Search", "Syntax Highlighting", "Multilingual", "Social", "Blog", "RSS", "Customization"]
-min_version = "0.111.0"
+min_version = "0.124.0"
 
 [author]
   name = "Xin"