Fonts3 - Autoloading fonts from Google Fonts

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)

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

examples/fonts-auto/mkdocs.yml

@@ -0,0 +1,46 @@
+# Copyright (c) 2016-2024 Martin Donath <[email protected]>
+#                         Alex Voss <[email protected]>
+
+# 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 &copy; 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
+

examples/fonts-auto/requirements.txt

@@ -0,0 +1,21 @@
+# Copyright (c) 2016-2023 Martin Donath <[email protected]>
+
+# 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

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