From a53900581643ae866996b2a3ce235e1775d9356c Mon Sep 17 00:00:00 2001 From: squidfunk Date: Thu, 16 Jul 2020 23:55:37 +0200 Subject: [PATCH] Added guide for font configuration --- docs/getting-started/customization.md | 2 +- docs/{ => getting-started}/data-privacy.md | 2 +- docs/guides/changing-the-fonts.md | 90 ++++++++++++++++++---- mkdocs.yml | 3 +- 4 files changed, 79 insertions(+), 18 deletions(-) rename docs/{ => getting-started}/data-privacy.md (97%) diff --git a/docs/getting-started/customization.md b/docs/getting-started/customization.md index 8c16b1de1..3134492f0 100644 --- a/docs/getting-started/customization.md +++ b/docs/getting-started/customization.md @@ -157,7 +157,7 @@ Material for MkDocs provides the following template blocks: | `content` | Wraps the main content | | `disqus` | Wraps the disqus integration | | `extrahead` | Empty block to define additional meta tags | -| `fonts` | Wraps the webfont definitions | +| `fonts` | Wraps the font definitions | | `footer` | Wraps the footer with navigation and copyright | | `header` | Wraps the fixed header bar | | `hero` | Wraps the hero teaser (if available) | diff --git a/docs/data-privacy.md b/docs/getting-started/data-privacy.md similarity index 97% rename from docs/data-privacy.md rename to docs/getting-started/data-privacy.md index a28ffca54..2f2e4986d 100644 --- a/docs/data-privacy.md +++ b/docs/getting-started/data-privacy.md @@ -30,7 +30,7 @@ Neue** and **Monaco** with their corresponding fall backs, relying on system fonts. You can easily include your own, self-hosted webfont by [overriding][4] the `fonts` block. - [2]: getting-started.md#fonts + [2]: ../guides/changing-the-fonts.md [3]: https://github.com/google/fonts/issues/1495 [4]: customization.md#overriding-template-blocks diff --git a/docs/guides/changing-the-fonts.md b/docs/guides/changing-the-fonts.md index deb008461..e874650d9 100644 --- a/docs/guides/changing-the-fonts.md +++ b/docs/guides/changing-the-fonts.md @@ -4,35 +4,95 @@ template: overrides/main.html # Changing the fonts +Material for MkDocs makes it easy to change the typeface of your project +documentation, as it directly integrates with [Google Fonts][1]. Alternatively, +fonts can be custom-loaded if self-hosting is preferred or another destination +should be used. + + [1]: https://fonts.google.com + ## Configuration -> Default: `Roboto` and `Roboto Mono` +### Regular font -The [Roboto font family][1] is the default font included with the theme, -specifically the regular sans-serif type for text and the `monospaced` type for -code. Both fonts are loaded from [Google Fonts][2] and can be changed to any -supported typeface, like for example the [Ubuntu font family][3]: +[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: [`Roboto`][3] + +The _regular font_ is used for all body copy, headlines, and essentially +everything that does not need to be proportionally spaced. It can be set to any +valid [Google Font][1] with: ``` yaml theme: font: - text: Ubuntu - code: Ubuntu Mono + text: Roboto ``` -The text font will be loaded in weights 400 and **700**, the `monospaced` font -in regular weight. If you want to load fonts from other destinations or don't -want to use Google Fonts for data privacy reasons, just set `font` to `false`: +The typeface will be loaded in 300, 400, *400i* and **700**. + + [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L120-L139 + [3]: https://fonts.google.com/specimen/Roboto + +### Proportional font + +[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: +[`Roboto Mono`][4] + +The _proportional font_ is used for code blocks and can be configured separately. +Just like the regular font, it can be set to any valid [Google Font][1] from +`mkdocs.yml` with: + +``` yaml +theme: + font: + code: Roboto Mono +``` + +The typeface will be loaded in 400. + + [4]: https://fonts.google.com/specimen/Roboto+Mono + +## Customization + +If you want to load fonts from other destinations or don't want to use Google +Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, add the following lines +to `mkdocs.yml`: ``` yaml theme: font: false ``` - [1]: https://fonts.google.com/specimen/Roboto - [2]: https://fonts.google.com - [3]: https://fonts.google.com/specimen/Ubuntu +This will prevent typefaces from being loaded from Google Fonts. As a fallback, +common system fonts will be used automatically. Additionally, if you want to +load a font from another destination, you can either [override the `fonts` +block][6] with a `style` tag, or use an [additional stylesheet][7] to add the +necessary `@font-face` definition: -## Customization +``` css +@font-face { + font-family: ""; + src: "..."; +} +``` -TBD +The font can then be configured to be used as the regular or proportional font: + +=== "Regular" + + ``` css + body, input { + font-family: "", -apple-system, Helvetica, Arial, sans-serif; + } + ``` + +=== "Proportional" + + ``` css + pre, code, kbd { + font-family: "", SFMono-Regular, Consolas, Menlo, monospace; + } + ``` + + [5]: ../getting-started/data-privacy.md + [6]: ../getting-started/customization.md#overriding-blocks + [7]: ../getting-started/customization.md#additional-stylesheets diff --git a/mkdocs.yml b/mkdocs.yml index f228d8175..5805a9e47 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -133,6 +133,7 @@ nav: - Publishing your site: getting-started/publishing-your-site.md - Customization: getting-started/customization.md - Troubleshooting: getting-started/troubleshooting.md + - Data privacy: getting-started/data-privacy.md - Guides: - Changing colors: guides/changing-colors.md - Changing the fonts: guides/changing-the-fonts.md @@ -161,7 +162,7 @@ nav: - Upgrading to 5.x: releases/5.md - Upgrading to 4.x: releases/4.md - Changelog: releases/changelog.md - # - Data privacy: data-privacy.md + # - Contributing: contributing.md # - License: license.md