Navbar styling fixes and updated documentation

Author: chalin

.vscode/cspell.json

@@ -15,6 +15,7 @@
     "hugo",
     "isset",
     "markdownify",
+    "navbars",
     "nvmrc",
     "Occitan",
     "refcache",

assets/js/base.js

@@ -32,33 +32,23 @@ limitations under the License.
         return element.offset().top + element.outerHeight();
     }
 
-    // Bootstrap Fixed Header
-    $(function() {
-        var promo = $(".js-td-cover");
-        if (!promo.length) {
-            return
-        }
-
-        var promoOffset = bottomPos(promo);
-        var navbarOffset = $('.js-navbar-scroll').offset().top;
-
-        var threshold = Math.ceil($('.js-navbar-scroll').outerHeight());
-        if ((promoOffset - navbarOffset) < threshold) {
-            $('.js-navbar-scroll').addClass('navbar-bg-onscroll');
-        }
-
-
-        $(window).on('scroll', function() {
-            var navtop = $('.js-navbar-scroll').offset().top - $(window).scrollTop();
-            var promoOffset = bottomPos($('.js-td-cover'));
-            var navbarOffset = $('.js-navbar-scroll').offset().top;
-            if ((promoOffset - navbarOffset) < threshold) {
-                $('.js-navbar-scroll').addClass('navbar-bg-onscroll');
-            } else {
-                $('.js-navbar-scroll').removeClass('navbar-bg-onscroll');
-                $('.js-navbar-scroll').addClass('navbar-bg-onscroll--fade');
-            }
-        });
+    // Navbar transparency over cover images
+    $(function () {
+      const promo = $('.js-td-cover');
+      if (!promo.length) return;
+      const navbar = $('.js-navbar-scroll');
+      if (!navbar.length) return;
+
+      const threshold = Math.ceil(navbar.outerHeight());
+
+      function adjustNavbarTransparency() {
+        const promoOffset = bottomPos(promo);
+        const navbarOffset = navbar.offset().top;
+        navbar.toggleClass('td-navbar-transparent', (promoOffset - navbarOffset) >= threshold);
+      }
+
+      adjustNavbarTransparency();
+      $(window).on('scroll', adjustNavbarTransparency);
     });
 
         // Navbar overflow detection with scroll indicators

assets/scss/td/_nav.scss

@@ -1,32 +1,25 @@
 //
 // Main navbar
 //
-// cSpell:ignore onscroll
 
-.td-navbar-cover {
-  @include media-breakpoint-up(md) {
-    background: transparent !important;
-
-    .nav-link {
-      text-shadow: 1px 1px 2px $dark;
-    }
-  }
-
-  &.navbar-bg-onscroll .nav-link {
-    text-shadow: none;
-  }
-}
-
-.navbar-bg-onscroll {
-  background: $primary !important;
-  opacity: inherit;
-}
+$td-navbar-bg-color: var(--bs-body-bg) !default;
 
 .td-navbar {
   @extend .navbar;
   @extend .navbar-expand;
 
-  background: $primary;
+  --td-navbar-bg-color: #{$td-navbar-bg-color};
+  --td-navbar-backdrop-filter: none;
+  --td-navbar-border-bottom: 1px solid var(--bs-border-color);
+
+  // To ensure that all child elements (such as form inputs) can inherit the
+  // right (light/dark) body color we set it explicitly here:
+  color: var(--bs-body-color);
+
+  background-color: var(--td-navbar-bg-color);
+  backdrop-filter: var(--td-navbar-backdrop-filter);
+  border-bottom: var(--td-navbar-border-bottom);
+
   min-height: 4rem;
   margin: 0;
   z-index: 32;
@@ -111,9 +104,11 @@
         &-text {
           display: none;
         }
+
         &-code {
           display: inline;
         }
+
         &::before {
           padding-right: 0;
         }
@@ -136,6 +131,21 @@
   }
 }
 
+.td-navbar-cover {
+  transition:
+    background-color 0.3s ease,
+    backdrop-filter 0.3s ease,
+    border-bottom 0.3s ease;
+
+  &.td-navbar-transparent {
+    @include media-breakpoint-up(md) {
+      --td-navbar-bg-color: transparent;
+      --td-navbar-backdrop-filter: blur(8px);
+      --td-navbar-border-bottom: none;
+    }
+  }
+}
+
 // Icons
 #main_navbar {
   li i {
@@ -147,6 +157,7 @@
       min-width: 1em;
     }
   }
+
   .alert {
     background-color: inherit;
     padding: 0;
@@ -226,6 +237,7 @@ nav.foldable-nav {
     font-size: 1em;
     color: var(--bs-secondary-color);
     transition: all 0.5s;
+
     &:hover {
       transform: rotate(90deg);
     }

assets/scss/td/_search.scss

@@ -42,15 +42,12 @@
     }
 
     &.form-control:focus {
-      border-color: tint-color($primary, 95%);
-      box-shadow: 0 0 0 2px tint-color($primary, 40%);
-      color: var(--bs-body-color);
+      color: inherit;
     }
 
     // Styling adjustments for the navbar
     @at-root {
       .td-navbar & {
-        border: none;
         color: inherit;
 
         @include placeholder {

assets/scss/td/_sidebar-tree.scss

@@ -156,7 +156,7 @@
   }
 
   &__search {
-    padding: 1rem 0;
+    padding: 1.5rem 0;
   }
 
   &__inner {

docsy.dev/assets/scss/_styles_project.scss

@@ -2,3 +2,33 @@
 @import 'td/code-dark';
 @import 'td/gcs-search-dark';
 @import 'local/blog';
+
+//
+// Color tuning for the Docsy website
+//
+
+// For dark navbars, use primary bg color by default (i.e., on mobile)
+@include color-mode(dark) {
+  &.td-navbar-cover {
+    --td-navbar-bg-color: #{$primary};
+    --td-navbar-border-bottom: none;
+
+    // Illustration of tinted transparent background color on desktop:
+    @include media-breakpoint-up(md) {
+      &.td-navbar-transparent {
+        $rgba-primary: rgba($primary, 0.25);
+        --td-navbar-bg-color: #{$rgba-primary};
+      }
+    }
+  }
+}
+
+// Add a border between the footer and page content for pages with dark content
+// in general (like the homepage), or in dark mode.
+.td-home,
+.td-section,
+.td-page {
+  .td-footer {
+    border-top: 1px solid var(--bs-border-color);
+  }
+}

docsy.dev/content/en/_index.md

@@ -1,6 +1,8 @@
 ---
 title: Docsy
 description: A Hugo theme for creating great technical documentation sites
+params:
+  ui: { navbar_theme: dark}
 ---
 
 {{% blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" %}}

docsy.dev/content/en/about/index.md

@@ -2,6 +2,8 @@
 title: About Docsy
 linkTitle: About
 menu: {main: {weight: 10}}
+params:
+  ui: { navbar_theme: dark}
 ---
 
 {{% blocks/cover title="About Docsy" height="auto" %}}

docsy.dev/content/en/blog/2026/0.14.0.md

@@ -8,7 +8,7 @@ author: >-
 message: Hello, world!
 body_class: release-highlights published-draft-post
 tags: [release]
-cSpell:ignore: Chalin pageinfo docsy gohugoio subrepo lookandfeel
+cSpell:ignore: Chalin pageinfo docsy gohugoio subrepo lightdark lookandfeel
 ---
 
 {{% card header="Highlights" %}}
@@ -40,6 +40,8 @@ Docsy [0.14.0] comes with the following notable features and improvements:
 - Review {{% _param BADGE BREAKING warning %}} changes:
   - {{% _param BREAKING %}} How you [customize Swagger](#swagger-scss) UI's look
     and feel changes.
+  - {{% _param BREAKING %}} Default [Navbar styles](#navbar) and how you
+    customize them changes.
   - {{% _param BREAKING %}} [Hugo 0.153+ upgrade](#hugo) introduces breaking
     changes
 - Review changes to internal files:
@@ -73,6 +75,53 @@ and how to customize the appearance of alerts, see [Alerts][].
 [alert shortcode]: /docs/content/shortcodes/#alert
 [Alerts]: /docs/content/adding-content/#alerts
 
+## {{% _param BREAKING %}} Navbar style improvements {#navbar}
+
+Prior to 0.14.0, the [navbar] element always used a [dark color theme][],
+regardless of the site's color theme or the active color mode. This restriction
+has been removed:
+
+- [Light/dark color theme][] is now configurable both site-wide and per page.
+
+The default navbar style now matches the base page style, offering a clean and
+consistent look and feel.[^navbar-bg-color]
+
+Learn more:
+
+- Default navbar style: [Navbar]
+- Navbar customization options: [Customizing the navbar][]
+
+[^navbar-bg-color]:
+    Prior to 0.14.0, the navbar background was set to the primary color.
+
+**Action may be required** to update your project in the following areas:
+
+- {{% _param BREAKING %}} Navbar theme now follows the page theme (default
+  `light`), instead of always forcing `dark`. Set `params.ui.navbar_theme` to
+  `dark` to restore the old behavior. [Details][navbar-lightdark-theme].
+
+- Review your project's navbar style overrides. The new style design, SCSS and
+  CSS variables may simplify your [customization][Customizing the navbar].
+
+- Review [_nav.html][] if your project overrides it.
+
+- Internal [navbar cover-image translucency][] class changes (update your custom
+  styles targeting these classes if present):
+  - `.td-navbar-transparent` replaces `.navbar-bg-on-scroll` (used with
+    `.td-navbar-cover`)
+  - `.navbar-bg-onscroll--fade` has been dropped: it was not used by Docsy, and
+    the transition effect is now handled by `.td-navbar-cover`
+
+[_nav.html]:
+  https://github.com/google/docsy/blob/main/layouts/_partials/navbar.html
+[Customizing the navbar]: /docs/content/lookandfeel/#navbar-customization
+[dark color theme]: /docs/content/lookandfeel/#lightdark-color-feature
+[Light/dark color theme]: /docs/content/lookandfeel/#navbar-lightdark-theme
+[navbar]: /docs/content/lookandfeel/#navbar
+[navbar-lightdark-theme]: /docs/content/lookandfeel/#navbar-lightdark-theme
+[navbar cover-image translucency]:
+  /docs/content/lookandfeel/#customize-over-cover
+
 ## Improved separation of project and internal SCSS files {#improved-scss-soc}
 
 Docsy 0.14.0 moves all internal SCSS files from `assets/scss/` into the
@@ -147,7 +196,7 @@ file.
 For details about style customizations, see [Project style files][] and
 [Advanced style customization][].
 
-## {{% _param BREAKING %}} Swagger UI style customization {#swagger-scss}
+### {{% _param BREAKING %}} Swagger UI style customization {#swagger-scss}
 
 Prior to 0.14.0, the Docsy User Guide incorrectly recommended overriding
 `_swagger.scss` to customize [Swagger UI][] styles. Docsy's internal SCSS files