Skip to content
This repository was archived by the owner on Nov 6, 2025. It is now read-only.

Commit 2c9c0ee

Browse files
alexvossalexvoss
authored
built-in fonts and custom fonts examples (#11)
+examples using built-in browser fonts +custom fonts custom fonts from CDN or locally hosted also points our use of privacy plugin
1 parent 54d0fa7 commit 2c9c0ee

8 files changed

Lines changed: 440 additions & 0 deletions

File tree

‎examples/fonts-builtin/docs/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Using built-in browser fonts
2+
3+
This example shows what happens when auto-loading of fonts from Google
4+
is turned off and no other fonts are configured:
5+
6+
regular - __bold__ - *italic* - __*bold italic*__ - `code`
7+
8+
You can inspect which fonts are actually used by your browser by using
9+
the built-in web developer tools (available at least in Chrome, Firefox,
10+
Safari, Edge) and choosing the fonts view. Try this with multiple
11+
browsers and compare the results to see if using only built-in fonts
12+
is an option for you.
13+
14+
## How it works
15+
16+
Turn off the default use of Roboto fonts loaded from Google Fonts in
17+
your `mkdocs.ym`:
18+
19+
```
20+
theme:
21+
font: false
22+
```
23+
24+
The fonts used are those that are built into the web browser.
25+
Material for MkDocs provides sensible defaults that should work in all
26+
common browsers.
27+
28+
## (Dis-)Advantages
29+
30+
Turning off Google Fonts means that your website will not cause
31+
browsers to make any font requests to Google, improving privacy.
32+
It also improves performance and network traffic, though browser
33+
caching means the advantages over fonts hosted on CDNs is small.
34+
35+
The downside is that you lose some control over the visual appearance
36+
of your website as different browsers will choose different fonts.
37+
38+
## Alternatives
39+
40+
!!! tip "Privacy Plugin"
41+
42+
The [privacy plugin] provided by Material for MkDocs provides a
43+
best-of-both-worlds solution in that it allows you to specify
44+
fonts available on Google Fonts directly in your `mkdocs.yml`.
45+
It automatically downloads the ones used and includes them in
46+
your website so they are served up by your own server.
47+
No need for a custom stylesheet.
48+
49+
An alternative is to turn off the use of Roboto from Google Fonts and
50+
then [configure custom fonts to use], as shown in [this example that shows
51+
how to switch to the Noto font family].
52+
53+
[privacy plugin]: https://squidfunk.github.io/mkdocs-material/plugins/privacy/
54+
[configure custom fonts to use]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/#additional-fonts
55+
[this example that shows how to switch to the Noto font family]: ../fonts-custom

‎examples/fonts-builtin/mkdocs.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
2+
# Alex Voss <alex@corealisation.com>
3+
4+
# Permission is hereby granted, free of charge, to any person obtaining a copy
5+
# of this software and associated documentation files (the "Software"), to
6+
# deal in the Software without restriction, including without limitation the
7+
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8+
# sell copies of the Software, and to permit persons to whom the Software is
9+
# furnished to do so, subject to the following conditions:
10+
11+
# The above copyright notice and this permission notice shall be included in
12+
# all copies or substantial portions of the Software.
13+
14+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16+
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
17+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19+
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20+
# IN THE SOFTWARE.
21+
22+
# -----------------------------------------------------------------------------
23+
# Recommended: set up configuration validation, see https://t.ly/xpZXU
24+
# -----------------------------------------------------------------------------
25+
26+
# Project information
27+
site_name: Using built-in browser fonts
28+
site_author: Alex Voss
29+
30+
# Copyright
31+
copyright: Copyright &copy; 2016 - 2023 Alex Voss and Martin Donath
32+
33+
# Theme
34+
theme:
35+
name: material
36+
font: false
37+
38+
# Markdown Extensions
39+
# (needed for this example, not for turning off Google Fonts)
40+
markdown_extensions:
41+
- admonition
42+
- pymdownx.details
43+
- pymdownx.superfences
44+

‎examples/fonts-builtin/requirements.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
2+
3+
# Permission is hereby granted, free of charge, to any person obtaining a copy
4+
# of this software and associated documentation files (the "Software"), to
5+
# deal in the Software without restriction, including without limitation the
6+
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
7+
# sell copies of the Software, and to permit persons to whom the Software is
8+
# furnished to do so, subject to the following conditions:
9+
10+
# The above copyright notice and this permission notice shall be included in
11+
# all copies or substantial portions of the Software.
12+
13+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
16+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18+
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
19+
# IN THE SOFTWARE.
20+
21+
mkdocs-material

‎examples/fonts-custom/docs/README.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Using a custom font
2+
3+
This example uses the Noto Serif and Noto Mono font families to show
4+
how custom fonts can be used. These families were chosen because the
5+
[Noto fonts are well documented] and they are available under the
6+
[Open Font License].
7+
8+
[Noto fonts are well documented]: https://notofonts.github.io/noto-docs/
9+
[Open Font License]: https://scripts.sil.org/ofl
10+
11+
In this example, the fonts are loaded from a CDN (that is not Google)
12+
to keep the example itself small and allow you to use it as a template
13+
for your own site, without assuming what fonts you might want to use.
14+
We also describe how to use custom fonts that are hosted on your own
15+
server, see below.
16+
17+
Here we have some text in:
18+
19+
- Noto Serif
20+
- **Noto Serif bold**
21+
- *Noto Serif italic*
22+
- __*Noto Serif bold italic*__
23+
- `Noto Mono`
24+
- __`Noto Mono bold`__
25+
26+
!!! tip "Privacy Plugin"
27+
28+
Before you consider the examples below, you should know that loading fonts
29+
or other assets from a CDN may bring you into non-compliance with data
30+
protection legislation such as the GDPR in the EU. You can read more about
31+
this in the [ensuring data privacy] section of the documentation.
32+
33+
The [privacy plugin] provided by Material for MkDocs provides a
34+
best-of-both-worlds solution in that it allows you to specify fonts
35+
available on Google Fonts directly in your `mkdocs.yml`. It automatically
36+
downloads the ones used and includes them in your website so they are served
37+
up together with your documentation. No need for a custom stylesheet.
38+
39+
[ensuring data privacy]: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy
40+
[privacy plugin]: https://squidfunk.github.io/mkdocs-material/plugins/privacy/
41+
42+
## How it works
43+
44+
In `mkdocs.yml`, turn off the auto-loading of fonts from Google Fonts
45+
and add an extra CSS stylesheet to configure your custom fonts.
46+
47+
```yaml
48+
theme:
49+
font: false
50+
51+
extra_css:
52+
- assets/stylesheets/extra.css
53+
```
54+
55+
Then, [configure custom fonts] hosted either on a CDN or on your own
56+
server, depending on your needs. We demonstrate this here with the
57+
Noto Sans and Noto Mono font families.
58+
59+
[configure custom fonts]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/#additional-fonts
60+
61+
### Using a CDN's CSS
62+
63+
If you are using a CDN to load your fonts, you may want to use CSS
64+
that the operators of the CDN are providing for defining the font
65+
faces, instead of writing your own. You still need to configure the
66+
fonts for Material to use, though:
67+
68+
=== "`mkdocs.yml`"
69+
70+
```yaml
71+
extra_css:
72+
- https://fonts.cdnfonts.com/css/noto-serif
73+
- https://fonts.cdnfonts.com/css/noto-mono
74+
- assets/stylesheets/extra.css
75+
```
76+
77+
=== "`extra.css`"
78+
79+
```css
80+
:root {
81+
--md-text-font: "Noto Serif";
82+
--md-code-font: "Noto Mono";
83+
}
84+
```
85+
86+
### Hosting on your own site
87+
88+
The code for hosting the fonts yourself as part of your site, looks
89+
very similar to the previous example that used a CDN. You need to
90+
write your own font face definitions and point the browser
91+
to the files located on your own server, e.g., in
92+
`docs/assets/fonts`:
93+
94+
=== "`mkdocs.yml`"
95+
96+
```yaml
97+
extra_css:
98+
- assets/stylesheets/extra.css
99+
```
100+
101+
=== "`extra.css`"
102+
103+
```css
104+
@font-face {
105+
font-family: "Noto Serif";
106+
font-weight: normal;
107+
font-style: normal;
108+
src: url("../fonts/NotoSerif-Regular.otf");
109+
}
110+
111+
@font-face {
112+
font-family: "Noto Serif";
113+
font-weight: bold;
114+
font-style: normal;
115+
src: url("../fonts/NotoSerif-Bold.otf");
116+
117+
}
118+
119+
@font-face {
120+
font-family: "Noto Serif";
121+
font-weight: normal;
122+
font-style: italic;
123+
src: url("../fonts/NotoSerif-Italic.otf");
124+
125+
}
126+
127+
@font-face {
128+
font-family: "Noto Mono";
129+
font-weight: normal;
130+
font-style: normal;
131+
src: url("../fonts/NotoSansMono-Regular.otf");
132+
133+
}
134+
135+
@font-face {
136+
font-family: "Noto Mono";
137+
font-weight: bold;
138+
font-style: normal;
139+
src: url("../fonts/NotoSansMono-Bold.otf");
140+
}
141+
142+
:root {
143+
--md-text-font: "Noto Serif";
144+
--md-code-font: "Noto Mono";
145+
}
146+
```
147+
148+
149+
## (Dis-)Advantages
150+
151+
If you are loading the fonts from a CDN as in this example, you are still not
152+
limiting traffic to only your website. To do that you would need to host the
153+
fonts as part of your site as described above. We include the CDN example here
154+
because you may have other reasons to use a CDN other than Google Fonts.
155+
156+
Try not to use too many different fonts as that will slow down your page load
157+
and rendering times.
158+
159+
Compared to using built-in browser fonts only, you have more control over the
160+
look of your site.
161+
162+
## Alternatives
163+
164+
Alternatively, you can simply [use built-in browser fonts] but that
165+
does mean giving up some control over the look of your site.
166+
167+
[use built-in browser fonts]: ../fonts-builtin

‎examples/fonts-custom/docs/assets/stylesheets/extra.css‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
@font-face {
2+
font-family: "Noto Serif";
3+
font-weight: normal;
4+
font-style: normal;
5+
src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSerif/unhinted/otf/NotoSerif-Regular.otf");
6+
}
7+
8+
@font-face {
9+
font-family: "Noto Serif";
10+
font-weight: bold;
11+
font-style: normal;
12+
src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSerif/unhinted/otf/NotoSerif-Bold.otf");
13+
14+
}
15+
16+
@font-face {
17+
font-family: "Noto Serif";
18+
font-weight: normal;
19+
font-style: italic;
20+
src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSerif/unhinted/otf/NotoSerif-Italic.otf");
21+
22+
}
23+
24+
@font-face {
25+
font-family: "Noto Mono";
26+
font-weight: normal;
27+
font-style: normal;
28+
src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSansMono/unhinted/otf/NotoSansMono-Regular.otf");
29+
30+
}
31+
32+
@font-face {
33+
font-family: "Noto Mono";
34+
font-weight: bold;
35+
font-style: normal;
36+
src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSansMono/unhinted/otf/NotoSansMono-Bold.otf");
37+
}
38+
39+
:root {
40+
--md-text-font: "Noto Serif";
41+
--md-code-font: "Noto Mono";
42+
}
43+

‎examples/fonts-custom/docs/assets/stylesheets/extra_local.css‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
@font-face {
2+
font-family: "Noto Serif";
3+
font-weight: normal;
4+
font-style: normal;
5+
src: url("../fonts/NotoSerif-Regular.otf");
6+
}
7+
8+
@font-face {
9+
font-family: "Noto Serif";
10+
font-weight: bold;
11+
font-style: normal;
12+
src: url("../fonts/NotoSerif-Bold.otf");
13+
14+
}
15+
16+
@font-face {
17+
font-family: "Noto Serif";
18+
font-weight: normal;
19+
font-style: italic;
20+
src: url("../fonts/NotoSerif-Italic.otf");
21+
22+
}
23+
24+
@font-face {
25+
font-family: "Noto Mono";
26+
font-weight: normal;
27+
font-style: normal;
28+
src: url("../fonts/NotoSansMono-Regular.otf");
29+
30+
}
31+
32+
@font-face {
33+
font-family: "Noto Mono";
34+
font-weight: bold;
35+
font-style: normal;
36+
src: url("../fonts/NotoSansMono-Bold.otf");
37+
}
38+
39+
:root {
40+
--md-text-font: "Noto Serif";
41+
--md-code-font: "Noto Mono";
42+
}
43+

0 commit comments

Comments
 (0)