Document how to use a non-Google font

Fixes #1968
r-lib · Apr 17, 2024 · b374acd · b374acd
1 parent a33d9d3
commit b374acd
Showing 1 changed file with 50 additions and 10 deletions.
diff --git 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 `<head>` using this syntax:
 
-``` yaml
+    ```yaml
+    template:
+    includes:
+      in_header: <link rel="stylesheet" type="text/css" href="https://..." />
+    ```
+
+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: