Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document how to use a non-Google font #2461

Merged
merged 3 commits into from
Apr 19, 2024
+52 −10
Merged

Document how to use a non-Google font #2461

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b374acd
Document how to use a non-Google font
hadley Apr 17, 2024
acb3b83
Feedback from code review.
hadley Apr 18, 2024
027eecb
Update vignettes/customise.Rmd
hadley Apr 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 52 additions & 10 deletions vignettes/customise.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:

* As a block of CSS which you should put in `pkgdown/extra.scss` or `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://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:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* As a link to a style file, which you'll need to add to the `<head>` using this syntax:
* As a link to a style file that you might use for another website, which you'll need to add to the `<head>` using this syntax:

would this be the use case?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was inspired by https://cocktails.hadley.nz, which uses typography.com, which gives you a stylesheet that you need to put in the head. Given that I only have two examples of using non-Google webfonts and they're both totally different, I don't want to get too specific in this vignette.


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:
includes:
in_header: <link rel="stylesheet" type="text/css" href="https://..." />
```

``` yaml
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:
Expand Down
Loading