Document how to use a non-Google font (#2461)

Fixes #1968
r-lib · Apr 19, 2024 · cb815fd · cb815fd
1 parent b047417
commit cb815fd
Showing 1 changed file with 52 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,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 `<head>` using this syntax:
+
+    ```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
 ```
 
+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: