Skip to content

Commit 4e94727

Browse files
evanwillevanwill
committed
document adding a custom font
1 parent eb3c74e commit 4e94727

File tree

2 files changed

+164
-2
lines changed

2 files changed

+164
-2
lines changed

‎docs/advanced/add-font.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: Custom Fonts
3+
parent: Advanced
4+
nav_order: 13
5+
---
6+
7+
# Add a Custom Font via CDN
8+
9+
Bootstrap uses a ["native font stack"](https://getbootstrap.com/docs/5.3/content/reboot/#native-font-stack) that provides efficient and consistent rendering across devices.
10+
However, one way to make your collection site more distinct is to customize the font.
11+
12+
Web font services (or font CDN) efficiently deliver font files to users so your custom font will show up the same across any device.
13+
The most popular is [Google Fonts](https://fonts.google.com/), although there are many alternatives (e.g. [Bunny Fonts](https://fonts.bunny.net/) is a more privacy oriented option that is almost identical).
14+
These instructions follow the Google Fonts interface, but other platforms will have a similar workflow.
15+
16+
*Note:* for a fully self contained collection, it is also possible to download copies of the fonts and add them to your project directly.
17+
18+
## Choose a Font
19+
20+
On your web font service ([Google Fonts](https://fonts.google.com/)) browse the available fonts to find one that fits your project style.
21+
Consider the readability, width, and height of the font since this will impact the useability of your site.
22+
23+
Once you have found a good option, click on the font to visit the font's home page.
24+
For example, [National Park](https://fonts.google.com/specimen/National+Park).
25+
26+
- Click "Get font" button.
27+
- Click "Get embed code" button. This will provide two code boxes: a CDN link for the font stylesheet and a CSS class. You will need to copy some values from these boxes into your project.
28+
29+
## Add to Your CB Project
30+
31+
There are a number of methods to add the custom font to your collection depending on your needs.
32+
Two options are described below:
33+
34+
- Using "theme.yml" -- this is the simplest option when using one font.
35+
- Using "_custom.scss" -- slightly more advanced option allowing multiple fonts and classes.
36+
37+
### Using theme.yml
38+
39+
This is the simplest approach and will render all text on your site with a single custom font.
40+
Ensure you have only one font selected (if you have more than one, remove the extras).
41+
42+
In your CB project, open the file "_data/theme.yml".
43+
Towards the bottom of the file, look for the Theme Fonts section.
44+
You will need to add values to `base-font-family` and `font-cdn`.
45+
46+
#### Add base-font-family
47+
48+
Look at the font embed code on Google Fonts.
49+
In the "CSS class" code box, you will see something like:
50+
51+
```
52+
.national-park-<uniquifier> {
53+
font-family: "National Park", sans-serif;
54+
font-optical-sizing: auto;
55+
font-weight: <weight>;
56+
font-style: normal;
57+
}
58+
```
59+
60+
Copy the value after `font-family:` and paste it into "theme.yml" after `base-font-family:`.
61+
Do not include the semicolon `;`.
62+
If the value has a comma in it, you will need to put quotes around it--if the value uses double quotes, use single quotes, or the reverse.
63+
For example, for National Park font, the "theme.yml" will look like:
64+
65+
```
66+
base-font-family: '"National Park", sans-serif'
67+
```
68+
69+
Note that "National Park" has double quotes around it and a comma with a fallback font.
70+
To ensure that value is useable to Jekyll, single quotes must go around the text.
71+
72+
#### Add font-cdn
73+
74+
Next, look back at the font embed code on Google Fonts.
75+
In the "Embed code in the head" box, you will see something like:
76+
77+
```
78+
<link rel="preconnect" href="https://fonts.googleapis.com">
79+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
80+
<link href="https://fonts.googleapis.com/css2?family=National+Park:[email protected]&display=swap" rel="stylesheet">
81+
```
82+
83+
Copy the full value and paste it into "theme.yml" after `font-cdn:`.
84+
Delete the line breaks between the different `<link` tags to make it all one line.
85+
For example, for National Park font, the "theme.yml" will look like:
86+
87+
```
88+
font-cdn: <link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=National+Park:[email protected]&display=swap" rel="stylesheet">
89+
```
90+
91+
### Using _custom.scss
92+
93+
For more complicated uses you will want to add custom styles to "_sass/_custom.scss".
94+
For example we may want a separate font for headers and body text.
95+
96+
In your web font service, select the two (or more) fonts, then look at the embed code boxes.
97+
The web service will provide a single embed code that loads all the selected fonts together.
98+
99+
First, you will need to add the fonts CDN so they can load.
100+
This can be done in one of two ways depending on the options provided by your web font service:
101+
102+
- If provided as `<link` stylesheet, copy the embed code and paste it into "_includes/head/head.html" in your project, around line 17 above the other CSS `<link` tags.
103+
- If provided as `@import` CSS, copy the `@import` statement and paste it into "_sass/_custom.scss" in your project.
104+
105+
Second, you will write some custom styles to apply the fonts to content on your site.
106+
Open "_sass/_custom.scss" to write the styles, pasting in the embed examples provided by your service and customizing to your needs.
107+
108+
#### Two Font Example
109+
110+
For example, let's add [Roboto](https://fonts.google.com/specimen/Roboto) as body font and [Orbitron](https://fonts.google.com/specimen/Orbitron) for headings.
111+
112+
First, you would select the two fonts on Google Fonts and click "Get embed code" and look at the boxes.
113+
Select the "@import" option to switch the embed code to CSS.
114+
You will see something like:
115+
116+
```
117+
<style>
118+
@import url('https://fonts.googleapis.com/css2?family=Orbitron:[email protected]&family=Roboto:ital,wght@0,100..900;1,100..900&display=swap');
119+
</style>
120+
```
121+
122+
Copy the `@import` line (not the `<style` tags) and paste it into the "_sass/_custom.scss" in your project.
123+
For each font, you will see a CSS class that looks something like:
124+
125+
```
126+
.orbitron-<uniquifier> {
127+
font-family: "Orbitron", sans-serif;
128+
font-optical-sizing: auto;
129+
font-weight: <weight>;
130+
font-style: normal;
131+
}
132+
```
133+
134+
Copy the CSS classes for each font and paste them into "_sass/_custom.scss" as well.
135+
Then edit those CSS classes for your use case by changing the selector and weight.
136+
137+
In this example, we want Roboto for the main font, so for selector we will use `body` which will override the Bootstrap defaults.
138+
For headings we want Orbitron, so for selector we will use `.h1,.h2,.h3,.h4,.h5,.h6,h1,h2,h3,h4,h5,h6` to match how Bootstrap sets the heading fonts.
139+
For weight we will use the standard "normal" of `400`.
140+
141+
Put together in "_custom.scss" it will look like:
142+
143+
```
144+
@import url('https://fonts.googleapis.com/css2?family=Orbitron:[email protected]&family=Roboto:ital,wght@0,100..900;1,100..900&display=swap');
145+
146+
body {
147+
font-family: "Roboto", sans-serif;
148+
font-optical-sizing: auto;
149+
font-weight: 400;
150+
font-style: normal;
151+
font-variation-settings:
152+
"wdth" 100;
153+
}
154+
.h1,.h2,.h3,.h4,.h5,.h6,h1,h2,h3,h4,h5,h6 {
155+
font-family: "Orbitron", sans-serif;
156+
font-optical-sizing: auto;
157+
font-weight: 400;
158+
font-style: normal;
159+
}
160+
```
161+
162+
Other common selectors would be `.display-1` (which would override just the main title font) or to use the font name (e.g. `.roboto-font`) to apply the font as a custom class only to specific elements.

‎docs/theme/advanced.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,10 @@ link-color: "#17a2b8"
8888
### base-font-family:
8989

9090
- Changes the font family
91-
- If you use this option, you will generally also need to use the font-cdn option below to add the font style sheet link to the head. This ensures the user actually have the font you configured!
91+
- If you use this option, you will generally also need to use the font-cdn option below to add the font style sheet link to the head. This ensures the user actually have the font you configured! For more info, see [Custom Fonts](/cb-docs/docs/advanced/add-font/).
9292

9393
```yaml
94-
base-font-family: 'Roboto', sans-serif;
94+
base-font-family: "'Roboto', sans-serif"
9595
```
9696

9797
### font-cdn:

0 commit comments

Comments
 (0)