Refactor navbar and layout SCSS, update examples

.vscode/cspell.json

@@ -11,6 +11,7 @@
     "Gantt",
     "getenv",
     "GLFM",
+    "Goldydocs",
     "htmltest",
     "hugo",
     "isset",

assets/scss/td/_blog.scss

@@ -1,7 +1,7 @@
 .td-blog {
   .td-rss-button {
     @extend .btn;
-    @extend .btn-info;
+    @extend .btn-primary;
     @extend .btn-lg;
 
     border-radius: 2rem;

assets/scss/td/_boxes.scss

@@ -43,6 +43,11 @@
 }
 
 // Common min-height modifiers used for boxes.
+//
+// Note that `auto` and `auto-from-top` do not set a min-height, so they are not
+// included in this mixin. But `auto` does affect the height, see the mixin
+// `td-main-height-auto` in `td/_main-container.scss`.
+
 @mixin td-box-height-modifiers($parent) {
   #{$parent} {
     &--height-min {

assets/scss/td/_color-adjustments-dark.scss

@@ -8,24 +8,42 @@
 // Usage: @import 'td/color-adjustments-dark'; // in client _styles_project.scss
 // =============================================================================
 
+// The following value makes sense for the Bootstrap base theme. Projects will
+// likely need to adjust this.
+$lighten-amount-for-dark-color-variant: 22% !default;
+$secondary-lighter: lighten($secondary, 30%) !default;
+
+// Make box-shadow color contrast more obvious in dark mode.
+// https://github.com/twbs/bootstrap/issues/39053 reports this issue.
+$box-shadow-alpha-dark: 0.8 !default;
+// Note: for some reason the following SCSS var must be a CSS var.
+$box-shadow-color-rgb-dark: var(--bs-black-rgb) !default;
+
+$primary-darker: shade-color(
+  $primary,
+  $lighten-amount-for-dark-color-variant
+) !default;
+
 @if $enable-dark-mode {
-  // The following value makes sense for the Bootstrap base theme. Projects will
-  // likely need to adjust this.
-  $lighten-amount-for-dark-color-variant: 22% !default;
-
-  $primary-dark: lighten(
-    $primary,
-    $lighten-amount-for-dark-color-variant
-  ) !default;
-  // $secondary-dark: lighten($secondary, $lighten-amount-for-dark-color-variant) !default;
-  // $success-dark: lighten($success, $lighten-amount-for-dark-color-variant) !default;
-  // $info-dark: lighten($info, $lighten-amount-for-dark-color-variant) !default;
-  // $warning-dark: lighten($warning, $lighten-amount-for-dark-color-variant) !default;
-  // $danger-dark: lighten($danger, $lighten-amount-for-dark-color-variant) !default;
-
-  [data-bs-theme='dark'] {
-    --bs-primary: #{$primary-dark} !important;
-    // --bs-success: #{$success-dark} !important;
+  @include color-mode(dark) {
+    $box-shadow-color-rgba-dark: rgba(
+      #{$box-shadow-color-rgb-dark},
+      #{$box-shadow-alpha-dark}
+    ) !default;
+
+    // The following is supposed to only tweak the rgba value, but Bootstrap isn't
+    // setup to allow this. So we'll need to ensure that non-rgba values stay in
+    // sync with Bootstraps.
+
+    --bs-box-shadow: 0 0.5rem 1rem #{$box-shadow-color-rgba-dark};
+    --bs-box-shadow-sm: 0 0.125rem 0.25rem #{$box-shadow-color-rgba-dark};
+    --bs-box-shadow-lg: 0 1rem 3rem #{$box-shadow-color-rgba-dark};
+    --bs-box-shadow-inset: inset 0 1px 2px #{$box-shadow-color-rgba-dark};
+
+    // --------------------------------
+
+    --bs-primary: #{$primary-darker} !important;
+    --bs-secondary: #{$secondary-lighter} !important;
   }
 
   // ---------------------------------------------------------------------------
@@ -44,5 +62,5 @@
   // }
 
   // Want to see the var value? Try:
-  // @warn "primary-dark: #{$primary-dark}";
+  // @warn "primary-darker: #{$primary-darker}";
 }

assets/scss/td/_extra.scss

@@ -0,0 +1,45 @@
+// Experimental extra styles that projects can test run.
+// These styles might eventually be merged into the core Docsy theme.
+
+// ------------------------------------------------------------
+// Navbar
+// ------------------------------------------------------------
+// Use underline decoration for active and hover nav-link states.
+
+.td-navbar {
+  .nav-link {
+    &.active,
+    &:hover {
+      text-decoration: $link-decoration;
+      text-decoration-color: rgba(
+        var(--bs-primary-rgb),
+        var(--bs-link-underline-opacity)
+      ) !important;
+      text-decoration-thickness: 3px;
+      text-underline-offset: map-get($td-link-underline-offsets, 3);
+    }
+
+    &:hover {
+      text-decoration-color: rgba(
+        var(--bs-secondary-rgb),
+        var(--bs-link-underline-opacity)
+      ) !important;
+      text-underline-offset: map-get($td-link-underline-offsets, 4);
+    }
+  }
+
+  &.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) {
+        --bs-bg-opacity: 0.75;
+        --td-navbar-backdrop-filter: blur(8px);
+        --td-navbar-border-bottom: none;
+      }
+    }
+  }
+}

assets/scss/td/_main-container.scss

@@ -5,12 +5,26 @@
   min-height: 100vh;
 }
 
+// Prior to 0.14.0, `auto` meant auto height from the top of the viewport. Since
+// 0.14.0, `auto` means auto height from the bottom of the navbar. Use
+// `auto-from-top` for the legacy behavior.
+@mixin td-main-height-auto {
+  margin-top: $td-navbar-min-height;
+  padding-top: $td-block-space-top-base !important;
+}
+
 // The outer page container for the default base template.
 .td-default {
   main {
     > section:first-of-type {
       @include media-breakpoint-up(md) {
-        padding-top: 8rem;
+        padding-top: calc(
+          #{$td-navbar-min-height} + #{$td-block-space-top-base}
+        );
+
+        &.td-box--height-auto {
+          @include td-main-height-auto;
+        }
       }
     }
 
@@ -22,13 +36,23 @@
 
 .td-main {
   flex-grow: 1;
+
+  &--height-auto {
+    margin-top: $td-navbar-min-height;
+    padding-top: $td-block-space-top-base !important;
+  }
+
+  // Use auto-top for legacy behavior of td-blocks-cover and td-box, use:
+  // &--height-auto-from-top { }
 }
 
 .td-404 main,
 .td-main main {
-  padding-top: 1.5rem;
+  --td-main-padding-top: 1.5rem;
+
+  padding-top: var(--td-main-padding-top);
   padding-bottom: 2rem;
   @include media-breakpoint-up(md) {
-    padding-top: 5.5rem;
+    padding-top: calc(var(--td-main-padding-top) + #{$td-navbar-min-height});
   }
 }

assets/scss/td/_nav.scss

@@ -2,12 +2,24 @@
 // Main navbar
 //
 
-$td-navbar-bg-color: var(--bs-body-bg) !default;
+$td-navbar-bg-color: rgba(var(--bs-body-bg-rgb), var(--bs-bg-opacity)) !default;
+$td-navbar-min-height: 4rem !default;
+
+// Should match Bootstrap's $link-underline-offset, see
+// https://getbootstrap.com/docs/5.3/utilities/link/#sass-utilities-api
+$td-link-underline-offsets: (
+  1: 0.125em,
+  2: 0.25em,
+  3: 0.375em,
+  4: 0.5em,
+) !default;
 
 .td-navbar {
   @extend .navbar;
   @extend .navbar-expand;
 
+  --bs-bg-opacity: 1;
+  --bs-link-underline-opacity: 0.75;
   --td-navbar-bg-color: #{$td-navbar-bg-color};
   --td-navbar-backdrop-filter: none;
   --td-navbar-border-bottom: 1px solid var(--bs-border-color);
@@ -20,21 +32,27 @@ $td-navbar-bg-color: var(--bs-body-bg) !default;
   backdrop-filter: var(--td-navbar-backdrop-filter);
   border-bottom: var(--td-navbar-border-bottom);
 
-  min-height: 4rem;
+  min-height: $td-navbar-min-height;
   margin: 0;
   z-index: 32;
 
   .navbar-brand {
-    text-transform: none;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+
+    &__logo {
+      display: flex;
+      align-items: center;
+    }
 
     &__name {
-      font-weight: $font-weight-bold;
+      font-weight: $font-weight-semibold;
     }
 
     svg {
-      display: inline-block;
-      margin: 0 10px;
-      height: 30px;
+      height: 2rem;
+      // width: auto;
     }
   }
 
@@ -43,8 +61,20 @@ $td-navbar-bg-color: var(--bs-body-bg) !default;
   }
 
   .nav-link {
-    text-transform: none;
-    font-weight: $font-weight-bold;
+    font-weight: $font-weight-semibold;
+
+    &:focus,
+    // Bootstrap sets .nav-link:focus-visible, but in a way that isn't
+    // compatible with dark mode. This is a known issue, see
+    // https://github.com/twbs/bootstrap/issues/37549:
+    //
+    // > Docs navbar blue focus visible is almost invisible!
+    //
+    // Fallback to browser default:
+    &:focus-visible {
+      outline: revert;
+      box-shadow: none;
+    }
   }
 
   // For .td-search__input styling, see _search.scss
@@ -65,6 +95,21 @@ $td-navbar-bg-color: var(--bs-body-bg) !default;
 
   @import '_navbar-mobile-scroll';
 
+  &.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) {
+        --bs-bg-opacity: 0.75;
+        --td-navbar-backdrop-filter: blur(8px);
+        --td-navbar-border-bottom: none;
+      }
+    }
+  }
+
   .td-light-dark-menu {
     position: unset !important;
     display: flex;
@@ -131,17 +176,20 @@ $td-navbar-bg-color: var(--bs-body-bg) !default;
   }
 }
 
-.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;
+@if $enable-dark-mode {
+  @include color-mode(dark) {
+    // Better contrast for dark homepage navbar links
+    &.td-navbar-cover {
+      .nav-link {
+        @at-root .td-home & {
+          // The homepage is the only page that does not have any navbar items
+          // that are active, because the user isn't viewing a page in any other
+          // section. Make nav-links more contrasted by setting all entries (which
+          // happen to be non-active) to the active color.
+          --bs-nav-link-color: var(--bs-navbar-active-color) !important;
+          --bs-nav-link-hover-color: var(--bs-navbar-active-color) !important;
+        }
+      }
     }
   }
 }

assets/scss/td/_sidebar-toc.scss

@@ -8,8 +8,8 @@
 
   @supports (position: sticky) {
     position: sticky;
-    top: 4rem;
-    height: calc(100vh - 4rem);
+    top: $td-navbar-min-height;
+    height: calc(100vh - #{$td-navbar-min-height});
     overflow-y: auto;
   }
 

assets/scss/td/_sidebar-tree.scss

@@ -120,7 +120,7 @@
   @include link-decoration;
 
   @include media-breakpoint-up(md) {
-    padding-top: 4rem;
+    margin-top: $td-navbar-min-height;
     padding-right: 1rem;
     border-right: 1px solid var(--bs-border-color);
   }
@@ -165,7 +165,7 @@
     @include media-breakpoint-up(md) {
       @supports (position: sticky) {
         position: sticky;
-        top: 4rem;
+        top: $td-navbar-min-height;
         z-index: 10;
       }
     }

assets/scss/td/_variables.scss

@@ -1,8 +1,5 @@
 // Bootstrap options
 
-$enable-gradients: true !default;
-$enable-shadows: true !default;
-
 :root,
 [data-bs-theme='light'] {
   --td-pre-bg: var(--bs-tertiary-bg);

assets/scss/td/blocks/_cover.scss

@@ -2,6 +2,12 @@
 
 @include td-box-height-modifiers('.td-cover-block');
 
+.td-cover-block {
+  &--height-auto {
+    @include td-main-height-auto;
+  }
+}
+
 .td-cover-logo {
   margin-right: 0.5em;
 }