From cb815fdbe6dbc5acfd7f569945a5e2b88e66cf02 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Fri, 19 Apr 2024 08:37:47 -0500 Subject: [PATCH] Document how to use a non-Google font (#2461) Fixes #1968 --- vignettes/customise.Rmd | 62 ++++++++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 10 deletions(-) diff --git a/vignettes/customise.Rmd b/vignettes/customise.Rmd index e4825ad6c..a2e56aa57 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,47 @@ 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: -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 block of CSS which you should put in `pkgdown/extra.scss` or `pkgdown/extra.css`. The CSS will look something like this: -``` yaml + ```css + @font-face { + font-family: "proxima-nova"; + src: + local("Proxima Nova Regular"), + local("ProximaNova-Regular"), + url("https://example.com/ProximaNova-Regular.eot?#iefix") format("embedded-opentype"), + url("https://example.com/fonts/proxima/ProximaNova-Regular.woff2") format("woff2"), + url("https://example.com/fonts/proxima/ProximaNova-Regular.woff") format("woff"), + url("https://example.com/fonts/proxima/ProximaNova-Regular.ttf") format("truetype"); + font-weight: normal; + font-style: normal; + font-display: fallback; + } + ``` + +* As a link to a style file, which you'll need to add to the `` using this syntax: + + ```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 ``` +Depending on where the font is from (and if you paid money for it), you may need to take additional steps to ensure that it can only be used from your site, and/or make sure that it can still be used when you're previewing locally. If you're having problems getting a custom font to work, looking for errors in the [browser developer console](https://developer.mozilla.org/en-US/docs/Glossary/Developer_Tools) is a good place to start. + +When iterating on fonts, you'll need to run `build_home_index(); init_site()` then refresh you browser to see the update. + + ### Syntax highlighting The colours used for syntax highlighting in code blocks are controlled by the `theme` setting: