Make an explicit switch for light switch and document

NEWS.md

@@ -1,6 +1,6 @@
 # pkgdown (development version)
 
-* The dark mode introduced in Bootstrap 5.3 can now be used in pkgdown sites based on work in bslib by @gadenbuie. See the customization vignette for details.
+* New light switch makes it easy for users to switch between light and dark themes for the website (based on work in bslib by @gadenbuie). See the customization vignette for details.
 * YAML validation has been substantially improved so you should get much clearer errors if you have made a mistake (#1927). Please file an issue if you find a case where the error message is not helpful.
 * `template_reference()` and `template_article()` now only add backticks to function names if needed (#2561).
 * Custom navbars that specify `icon` but not `aria-label` will now generate a message reminding you to provide one for to improve accessibility (#2533).

R/navbar-menu.R

@@ -210,7 +210,7 @@ navbar_html_text <- function(x) {
 
     icon <- html_tag("span", class = unique(c(iconset, classes)))
 
-    if (is.null(x$`aria-label`)) {
+    if (is.null(x$`aria-label`) && is.null(x$text)) {
       cli::cli_inform(
         c(
           x = "Icon {.str {x$icon}} lacks an {.var aria-label}.",

R/navbar.R

@@ -19,7 +19,7 @@ data_navbar <- function(pkg = ".", depth = 0L) {
 }
 
 uses_lightswitch <- function(pkg) {
-  !is.null(config_pluck_string(pkg, "template.theme-dark"))
+  config_pluck_bool(pkg, "template.light-switch", default = FALSE)
 }
 
 # Default navbar ----------------------------------------------------------
@@ -137,7 +137,7 @@ navbar_components <- function(pkg = ".") {
     menu$lightswitch <- menu_submenu(
       text = NULL,
       icon = "fa-sun",
-      label = tr_("Lightswitch"),
+      label = tr_("Light switch"),
       id = "lightswitch",
       list(
         menu_theme(tr_("Light"), icon = "fa-sun", theme = "light"),

R/theme.R

@@ -75,9 +75,9 @@ bs_theme <- function(pkg = ".", call = caller_env()) {
   files <- lapply(rules, sass::sass_file)
   bs_theme <- bslib::bs_add_rules(bs_theme, files)
 
-  # Add dark theme, if present
-  dark_theme <- config_pluck_string(pkg, "template.theme-dark")
-  if (!is.null(dark_theme)) {
+  # Add dark theme if needed
+  if (uses_lightswitch(pkg)) {
+   dark_theme <- config_pluck_string(pkg, "template.theme-dark", default = "arrow-dark")
     check_theme(
       dark_theme,
       error_pkg = pkg,

pkgdown/_pkgdown.yml

@@ -17,7 +17,7 @@ authors:
 
 template:
   bootstrap: 5
-  theme-dark: arrow-dark
+  light-switch: true
   bslib:
     primary: "#0054AD"
     border-radius: 0.5rem

vignettes/customise.Rmd

@@ -45,6 +45,17 @@ The following sections show you how.
 
 Please note that pkgdown's default theme has been carefully optimised to be accessible, so if you make changes, make sure that to also read `vignette("accessibility")` to learn about potential accessibility pitfalls.
 
+### Light switch
+
+You can provide a "light switch" to allow your uses to switch between dark and light themes by setting the `light-switch` template option to true:
+
+```yaml
+template:
+  light-switch: true
+```
+
+This will add a `lightswitch` component to the navbar, which defaults to appearing at the far right. This allows the user to select light mode, dark mode, or auto mode (which follows the system setting). The modes are applied using Bootstrap 5.3's [colours modes](https://getbootstrap.com/docs/5.3/customize/color-modes/) so are not separate themes, but a thin layer of colour customisation applied via CSS.
+
 ### Bootswatch themes
 
 The easiest way to change the entire appearance of your website is to use a [Bootswatch theme](https://bootswatch.com):
@@ -55,6 +66,8 @@ template:
   bootswatch: materia
 ```
 
+(Themes are unlikely to work with the light switch, but you can try it and see.)
+
 Changing the bootswatch theme affects both the HTML (via the navbar, more on that below) and the CSS, so you'll need to re-build your complete site with `build_site()` to fully appreciate the changes.
 While you're experimenting, you can speed things up by just rebuilding the home page and the CSS by running `build_home_index(); init_site()` (and then refreshing the browser).
 
@@ -97,6 +110,8 @@ For example, `table-border-color` defaults to `border-color` which defaults to `
 If you want to change the colour of all borders, you can set `border-color`; if you just want to change the colour of table borders, you can set `table-border-color`.
 You can find a full list of variables in the [bslib docs](https://rstudio.github.io/bslib/articles/bs5-variables/index.html).
 
+If you're using the light switch, [many colours](https://getbootstrap.com/docs/5.3/customize/color-modes/#sass-variables) are available for customisation specifically for the dark theme.
+
 Theming with bslib is powered by `bslib::bs_theme()` and the `bslib` field is a direct translation of the arguments to that function.
 As a result, you can fully specify a bslib theme using the `template.bslib` field, making it easy to share YAML with the `output.html_document.theme` field [of an R Markdown document](https://rstudio.github.io/bslib/articles/theming/index.html).
 
@@ -187,6 +202,15 @@ template:
   theme: arrow-dark
 ```
 
+If you're using the light switch, you will want to provide a `theme` and a `theme-dark`:
+
+```yaml
+template:
+  light-switch: true
+  theme: gruvbox-light
+  theme-dark: gruvbox-dark
+```
+
 The foreground and background colours used for inline code are controlled by `code-color` and `code-bg` bslib variables.
 If you want inline code to match code blocks, you'll need to override the variables yourself, e.g.: