feat: Use bslib's navbar Sass variables, if present (#2847)

NEWS.md

@@ -1,5 +1,6 @@
 # pkgdown (development version)
 
+* pkgdown now uses the same Sass variables as bslib to set the navbar background color: `$navbar-bg` for the background color in light and dark mode, or `$navbar-light-bg` and `$navbar-dark-bg` for individually controlling light and dark mode background colors. `pkgdown-navbar-bg` and `$pkgdown-navbar-bg-dark` both still provide pkgdown-specific overrides (@gadenbuie, #2847).
 * Code repositories hosted on Codeberg are now supported in the `BugReports` and `URL` fields (@nfrerebeau, #2843).
 * Articles (i.e., vignettes in `vignettes/articles`, created by `usethis::use_article()` and available on pkgdown sites but not included in a built package) have improved test cases (thanks to @venpopov and @ethanbass).
 * New `clean_site(force = TRUE)` for cleaning of `docs/` regardless of whether it was built by pkgdown (#2827).

inst/BS5/assets/pkgdown.scss

@@ -26,8 +26,13 @@
 
 /* navbar =================================================================== */
 
-$pkgdown-navbar-bg: null !default;
-$pkgdown-navbar-bg-dark: null !default;
+// pkgdown will follow bslib navbar variables by default
+$navbar-bg: null !default;
+$navbar-light-bg: if($navbar-bg, $navbar-bg, null) !default;
+$navbar-dark-bg: if($navbar-bg, $navbar-bg, null) !default;
+
+$pkgdown-navbar-bg: if($navbar-light-bg, $navbar-light-bg, null) !default;
+$pkgdown-navbar-bg-dark: if($navbar-dark-bg, $navbar-dark-bg, null) !default;
 
 // BS navbars appears to be designed with the idea that you have a coloured
 // navbar that looks the same in both light and dark mode. We prefer a mildly

vignettes/customise.Rmd

@@ -235,7 +235,7 @@ template:
 
 ### Navbar style
 
-The primary navbar colours are determined by HTML classes, not CSS, and can be customized using the `navbar` fields `bg` and `type` which control the background and foreground colours respectively.
+When [light-switch](#light-switch) is disabled, the primary navbar colours are determined by HTML classes, not CSS, and can be customized using the `navbar` fields `bg` and `type` which control the background and foreground colours respectively.
 Typically `bg` will be one of `light`, `dark`, or `primary`:
 
 ``` yaml
@@ -248,6 +248,17 @@ Similarly, you don't usually need to set `type` because bootstrap will guess it
 If the guess is wrong, you can override with `type: light` or `type: dark` depending on whether the background colour is light (so you need dark text) or `type: dark` if the background is dark (so you need light text).
 Unfortunately, these are defined relative to the page background, so if you have a dark site you'll need to flip `light` and `dark` (a little experimentation should quickly determine what looks best).
 
+When [light-switch](#light-switch) is enabled, navbar background colours can be customized via Sass variables provided to `template.bslib`.
+Use `$navbar-bg` to set a constant navbar colour in both light and dark mode, or `$navbar-light-bg` and `$navbar-dark-bg` to choose separate colours.
+
+```yaml
+template:
+  bslib:
+    # navbar-bg: "#306CC9"
+    navbar-light-bg: "#9CBAE7"
+    navbar-dark-bg: "#183663"
+```
+
 Because the navbar is styled with HTML, you'll need to `build_home_index(); init_site()` to see the effect of changing this parameter.
 
 ## Layout {#layout}