From dc1b802ab241880990140f6baf23702b9570ea7a Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Wed, 22 May 2024 13:06:51 -0500 Subject: [PATCH] Make an explicit switch for light switch and document --- NEWS.md | 2 +- R/navbar-menu.R | 2 +- R/navbar.R | 4 ++-- R/theme.R | 6 +++--- pkgdown/_pkgdown.yml | 2 +- vignettes/customise.Rmd | 24 ++++++++++++++++++++++++ 6 files changed, 32 insertions(+), 8 deletions(-) diff --git a/NEWS.md b/NEWS.md index 9c31a5ef7..b1e2304f0 100644 --- a/NEWS.md +++ b/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). diff --git a/R/navbar-menu.R b/R/navbar-menu.R index 05b4fb40c..b36964c9d 100644 --- a/R/navbar-menu.R +++ b/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}.", diff --git a/R/navbar.R b/R/navbar.R index f474576ef..1047b832b 100644 --- a/R/navbar.R +++ b/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"), diff --git a/R/theme.R b/R/theme.R index a5e4e89fd..485d0d950 100644 --- a/R/theme.R +++ b/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, diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 33c5535c4..10723d821 100644 --- a/pkgdown/_pkgdown.yml +++ b/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 diff --git a/vignettes/customise.Rmd b/vignettes/customise.Rmd index c3c691c75..04a71cfba 100644 --- a/vignettes/customise.Rmd +++ b/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.: