From 92f78cd48ab69de9eabfdcfc433790f8dff36d48 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Thu, 25 Apr 2024 15:54:04 +0200 Subject: [PATCH 1/3] added font auto-loading example --- examples/fonts-auto/docs/README.md | 48 ++++++++++++++++++++++++++++ examples/fonts-auto/mkdocs.yml | 46 ++++++++++++++++++++++++++ examples/fonts-auto/requirements.txt | 21 ++++++++++++ 3 files changed, 115 insertions(+) create mode 100644 examples/fonts-auto/docs/README.md create mode 100644 examples/fonts-auto/mkdocs.yml create mode 100644 examples/fonts-auto/requirements.txt diff --git a/examples/fonts-auto/docs/README.md b/examples/fonts-auto/docs/README.md new file mode 100644 index 0000000..2b2700b --- /dev/null +++ b/examples/fonts-auto/docs/README.md @@ -0,0 +1,48 @@ +# Auto-loading fonts from Google Fonts + +This example shows how you can automatically load fonts from Google Fonts by +simply choosing the font family in your configuration file. This example +uses Ubuntu for text and Ubuntu Mono for code. + +regular - __bold__ - *italic* - __*bold italic*__ - `code` + +You can inspect which fonts are actually used by your browser by using +the built-in web developer tools (available at least in Chrome, Firefox, +Safari, Edge) and choosing the fonts view. + +## How it works + +To replace the default font Roboto, specify the Ubuntu font or a font of your +choosing in your `mkdocs.yml`: + +```yaml +theme: + font: + text: Ubuntu + code: Ubuntu Mono +``` + +## (Dis-)advantages + +When you use Google Fonts, each page-load will result in a request being made to +Google Fonts. The alternatives below provide alternative approaches that are +more privacy preserving. + +## Alternatives + +!!! tip "Privacy Plugin" + + The [privacy plugin] provided by Material for MkDocs provides a + best-of-both-worlds solution in that it allows you to specify + fonts available on Google Fonts directly in your `mkdocs.yml`. + It automatically downloads the ones used and includes them in + your website so they are served up by your own server. + No need for a custom stylesheet. + +Another alternative is to turn off the use of Google Fonts and +[configure custom fonts to use] that you host yourself, as shown in +[this example that shows how to switch to the Noto font family]. + +[privacy plugin]: https://squidfunk.github.io/mkdocs-material/plugins/privacy/ +[configure custom fonts to use]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/#additional-fonts +[this example that shows how to switch to the Noto font family]: ../fonts-custom diff --git a/examples/fonts-auto/mkdocs.yml b/examples/fonts-auto/mkdocs.yml new file mode 100644 index 0000000..7fb2df0 --- /dev/null +++ b/examples/fonts-auto/mkdocs.yml @@ -0,0 +1,46 @@ +# Copyright (c) 2016-2024 Martin Donath +# Alex Voss + +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to +# deal in the Software without restriction, including without limitation the +# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +# sell copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: + +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. + +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. + +# ----------------------------------------------------------------------------- +# Recommended: set up configuration validation, see https://t.ly/xpZXU +# ----------------------------------------------------------------------------- + +# Project information +site_name: Auto-loading fonts from Google Fonts +site_author: Alex Voss + +# Copyright +copyright: Copyright © 2016 - 2024 Alex Voss and Martin Donath + +# Theme +theme: + name: material + font: + text: Ubuntu + code: Ubuntu Mono + +# Markdown Extensions +# (needed for this example, not for using Google Fonts) +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + diff --git a/examples/fonts-auto/requirements.txt b/examples/fonts-auto/requirements.txt new file mode 100644 index 0000000..df8b44f --- /dev/null +++ b/examples/fonts-auto/requirements.txt @@ -0,0 +1,21 @@ +# Copyright (c) 2016-2023 Martin Donath + +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to +# deal in the Software without restriction, including without limitation the +# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +# sell copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: + +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. + +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. + +mkdocs-material From 74efda8f11588608823ac5ddb117854b1757a2f9 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Thu, 25 Apr 2024 15:54:29 +0200 Subject: [PATCH 2/3] added links to font examples --- docs/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/index.md b/docs/index.md index 4f5b689..b640993 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,3 +8,8 @@ to be sure. [sponsors]: https://squidfunk.github.io/mkdocs-material/insiders/ [available features]: https://squidfunk.github.io/mkdocs-material/insiders/#whats-in-for-me + +* Fonts + - [Auto-Loading from Google Fonts](fonts-auto) + - [Builtin fonts](fonts-builtin) + - [Custom fonts](fonts-custom) From 02745b5300c8fb9d443c19ce62071f136d80c380 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Thu, 25 Apr 2024 15:54:51 +0200 Subject: [PATCH 3/3] language improvements --- examples/fonts-builtin/docs/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/examples/fonts-builtin/docs/README.md b/examples/fonts-builtin/docs/README.md index 6e067d9..84eb7b9 100644 --- a/examples/fonts-builtin/docs/README.md +++ b/examples/fonts-builtin/docs/README.md @@ -1,7 +1,7 @@ # Using built-in browser fonts -This example shows what happens when auto-loading of fonts from Google -is turned off and no other fonts are configured: +This example shows what happens when you turn off auto-loading of fonts from +Google and no other fonts are configured: regular - __bold__ - *italic* - __*bold italic*__ - `code` @@ -16,16 +16,16 @@ is an option for you. Turn off the default use of Roboto fonts loaded from Google Fonts in your `mkdocs.ym`: -``` +```yaml theme: font: false ``` The fonts used are those that are built into the web browser. Material for MkDocs provides sensible defaults that should work in all -common browsers. +common browsers. -## (Dis-)Advantages +## (Dis-)advantages Turning off Google Fonts means that your website will not cause browsers to make any font requests to Google, improving privacy. @@ -42,8 +42,8 @@ of your website as different browsers will choose different fonts. The [privacy plugin] provided by Material for MkDocs provides a best-of-both-worlds solution in that it allows you to specify fonts available on Google Fonts directly in your `mkdocs.yml`. - It automatically downloads the ones used and includes them in - your website so they are served up by your own server. + It automatically downloads the ones used and includes them in + your website so they are served up by your own server. No need for a custom stylesheet. An alternative is to turn off the use of Roboto from Google Fonts and