From b374acd751972c727a725cd1cfbb6e737d7de97d Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Wed, 17 Apr 2024 16:38:57 -0500 Subject: [PATCH] Document how to use a non-Google font Fixes #1968 --- vignettes/customise.Rmd | 60 ++++++++++++++++++++++++++++++++++------- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/vignettes/customise.Rmd b/vignettes/customise.Rmd index 48b56c484..f416a5e78 100644 --- a/vignettes/customise.Rmd +++ b/vignettes/customise.Rmd @@ -95,8 +95,24 @@ 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 `vignette("bs5-variables", package = "bslib")`. +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). + +``` yaml +template: + bslib: + version: 5 + bg: "#202123" + fg: "#B8BCC2" + primary: "#306cc9" +``` + +While iterating on colours and other variables you only need to rerun `init_site()` and refresh your browser to see the changes. + +### Fonts + You can also override the default fonts used for the majority of the text (`base_font`), for headings (`heading_font`) and for code (`code_font`). -The easiest way is to supply the name of a [Google font](https://fonts.google.com): +The easiest way is to supply the name of a [Google font](https://fonts.google.com) with the following syntax: ``` yaml template: @@ -107,21 +123,45 @@ template: code_font: {google: "JetBrains Mono"} ``` -While iterating on colours and other variables you only need to rerun `init_site()` and refresh your browser; when iterating on fonts, you'll need to run `build_home_index(); init_site()`. +If you want to use a non-Google font, you'll need to do a bit more work. There are two steps: you need to first configure the font with CSS and then use it in your `_pkgdown.yaml`. There are two ways you might get the CSS: + +* As a block of CSS which you should put in `pkgdown/extra.css`. The CSS will look something like this: + + ```css + @font-face { + font-family: "proxima-nova"; + src: + local("Proxima Nova Regular"), + local("ProximaNova-Regular"), + url("https://ropensci.org/fonts/proxima/ProximaNova-Regular.eot?#iefix") format("embedded-opentype"), + url("https://ropensci.org/fonts/proxima/ProximaNova-Regular.woff2") format("woff2"), + url("https://ropensci.org/fonts/proxima/ProximaNova-Regular.woff") format("woff"), + url("https://ropensci.org/fonts/proxima/ProximaNova-Regular.ttf") format("truetype"); + font-weight: normal; + font-style: normal; + font-display: fallback; + } + ``` -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). +* As a link to a style file, which you'll need to add to the `` using this syntax: -``` yaml + ```yaml + template: + includes: + in_header: + ``` + +Then in `_pkgdown.yml` you can use the name of the font you just specified: + +```yaml template: bslib: - version: 5 - bootswatch: lux - base_font: {google: "Roboto"} - heading_font: {google: "Roboto Slab"} - code_font: {google: "JetBrains Mono"} + base_font: proxima-nova ``` +When iterating on fonts, you'll need to run `build_home_index(); init_site()` then refresh you browwser to see the update. + + ### Syntax highlighting The colours used for syntax highlighting in code blocks are controlled by the `theme` setting: