Breadcrumb for blog pages, and per-page/section config (#2161)

Author: chalin

CHANGELOG.md

@@ -28,14 +28,25 @@ For the full list of changes, see the [0.x.y] release notes.
 
 **New**:
 
+- **[Breadcrumb navigation]** support has been enhanced and adjusted:
+  - You can now disable breadcrumbs for an entire project, or individual pages
+    or sections by setting `ui.breadcrumb_disable` to true. For details, see
+    [Breadcrumb navigation].
+  - **Blog** pages now also have breadcrumbs by default ([#1788]).
+  - Index-page single-element breadcrumb lists are hidden by default ([#2160]).
+
 **Other changes**:
 
-- Blog section index page content and title used to be ignored, they are now
+- **Blog** section index page content and title used to be ignored, they are now
   displayed ([#1787]). To recover the old behavior use the following style
   override: `.td-section.td-blog .td-content { display: none; }`.
 
 [0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y
 [#1787]: https://github.com/google/docsy/issues/1787
+[#1788]: https://github.com/google/docsy/issues/1788
+[#2160]: https://github.com/google/docsy/pull/2160
+[Breadcrumb navigation]:
+  https://www.docsy.dev/docs/adding-content/navigation/#breadcrumb-navigation
 
 ## 0.11.0
 

layouts/blog/baseof.html

@@ -27,6 +27,9 @@
               <i class="fa-solid fa-rss" aria-hidden="true"></i>
             </a>
             {{ end -}}
+            {{ if not (.Param "ui.breadcrumb_disable") -}}
+              {{ partial "breadcrumb.html" . -}}
+            {{ end -}}
             {{ block "main" . }}{{ end }}
           </main>
         </div>

layouts/docs/baseof.html

@@ -23,7 +23,9 @@
           </aside>
           <main class="col-12 col-md-9 col-xl-8 ps-md-5" role="main">
             {{ partial "version-banner.html" . }}
-            {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
+            {{ if not (.Param "ui.breadcrumb_disable") -}}
+              {{ partial "breadcrumb.html" . -}}
+            {{ end -}}
             {{ block "main" . }}{{ end }}
           </main>
         </div>

layouts/swagger/baseof.html

@@ -24,7 +24,9 @@
             {{ partial "taxonomy_terms_clouds.html" . }}
           </aside>
           <main class="col-12 col-md-9 col-xl-8 ps-md-5" role="main">
-            {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
+            {{ if not (.Param "ui.breadcrumb_disable") -}}
+              {{ partial "breadcrumb.html" . -}}
+            {{ end -}}
             <script src="https://unpkg.com/swagger-ui-dist@5.1.0/swagger-ui-bundle.js" integrity="sha384-TBW5qg/G561aZRk4jvscdaB7BEDK/9wpe/jS8vyKzK/ls+nJfWQw0W4cobLRYkWk" crossorigin="anonymous"></script>
             <script src="https://unpkg.com/swagger-ui-dist@5.1.0/swagger-ui-standalone-preset.js" integrity="sha384-cftHzufgeQ3yLXAwNPSMCBSqPUkItABWOchc20veg7pQ1sDu0FQSp0Grfx/BfhN7" crossorigin="anonymous"></script>
             {{ block "main" . }}{{ end }}

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

@@ -283,11 +283,27 @@ To create a placeholder page, create a page file as usual in the directory where
 
 ## Breadcrumb navigation
 
-Breadcrumb navigation links appear at the top of each page by default. To disable breadcrumb navigation, set site param `ui.breadcrumb_disable = true` in `hugo.toml`.
+[Breadcrumb navigation] appears at the top of each non-index page be default. To
+also display single-element breadcrumb lists in index pages, add the following
+[style override] to your project:
 
-Breadcrumb navigation links are also shown for each item on the taxonomy results page (i.e. when you click one of the taxonomy labels, e.g. Tags/Categories). These breadcrumbs can be disabled in `hugo.toml` by setting site param `ui.taxonomy_breadcrumb_disable = true`.
+```scss
+.td-breadcrumbs__single {
+  display: inline !important;
+}
+```
+
+[Breadcrumb navigation]: https://en.wikipedia.org/wiki/Breadcrumb_navigation
+[style override]: /docs/adding-content/lookandfeel/#project-style-files
+
+Breadcrumb navigation is also shown for each item in the taxonomy results page
+— that is, when you click one of the taxonomy labels such as _Categories_
+or _Tags_.
 
-The tabbed pane below lists the breadcrumb navigation options you can define in your project [configuration file].
+As illustrated next, you can disable (non-taxonomy) breadcrumb navigation for an
+entire project, by setting `ui.breadcrumb_disable` to true in your project
+[configuration file]. Similarly, you can disabled taxonomy breadcrumbs by
+setting `ui.taxonomy_breadcrumb_disable` to true:
 
 {{< tabpane >}}
 {{< tab header="Configuration file:" disabled=true />}}{{< tab header="hugo.toml" lang="toml" >}}
@@ -313,6 +329,17 @@ params:
 {{< /tab >}}
 {{< /tabpane >}}
 
+To disable breadcrumbs in a specific page or section set `ui.breadcrumb_disable`
+to true in the page or section-index front matter. Here is an example of the
+latter:
+
+```yaml
+cascade:
+  params:
+    ui:
+      breadcrumb_disable: true
+```
+
 ## Heading self links
 {.test-class}
 

userguide/content/en/project/_index.md

@@ -5,8 +5,9 @@ description: Docsy project design documentation and other resources
 outputs: [HTML]
 cascade:
   type: docs
-  # ui:
-  #   breadcrumb_disable: true
+  params:
+    ui:
+      breadcrumb_disable: true
 ---
 
 - Docsy build and design notes (TBC)

userguide/static/refcache.json

@@ -375,6 +375,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-01-07T17:47:01.735556-05:00"
   },
+  "https://github.com/google/docsy/issues/1788": {
+    "StatusCode": 206,
+    "LastSeen": "2025-01-08T13:26:59.139291-05:00"
+  },
   "https://github.com/google/docsy/issues/1812": {
     "StatusCode": 200,
     "LastSeen": "2024-11-06T12:03:52.305697-05:00"
@@ -563,6 +567,10 @@
     "StatusCode": 200,
     "LastSeen": "2024-11-06T12:04:13.893357-05:00"
   },
+  "https://github.com/google/docsy/pull/2160": {
+    "StatusCode": 206,
+    "LastSeen": "2025-01-08T13:26:59.610341-05:00"
+  },
   "https://github.com/google/docsy/pulls": {
     "StatusCode": 200,
     "LastSeen": "2024-11-06T12:03:15.642661-05:00"
@@ -1031,6 +1039,10 @@
     "StatusCode": 206,
     "LastSeen": "2024-11-06T12:08:17.225307-05:00"
   },
+  "https://www.docsy.dev/docs/adding-content/navigation/#breadcrumb-navigation": {
+    "StatusCode": 206,
+    "LastSeen": "2025-01-08T13:26:58.452656-05:00"
+  },
   "https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options": {
     "StatusCode": 206,
     "LastSeen": "2024-11-06T12:04:02.230446-05:00"