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

examples/fonts-builtin/docs/README.md

@@ -0,0 +1,55 @@
+# 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:
+
+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. Try this with multiple
+browsers and compare the results to see if using only built-in fonts
+is an option for you.
+
+## How it works
+
+Turn off the default use of Roboto fonts loaded from Google Fonts in
+your `mkdocs.ym`:
+
+```
+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. 
+
+## (Dis-)Advantages
+
+Turning off Google Fonts means that your website will not cause
+browsers to make any font requests to Google, improving privacy.
+It also improves performance and network traffic, though browser
+caching means the advantages over fonts hosted on CDNs is small.
+
+The downside is that you lose some control over the visual appearance
+of your website as different browsers will choose different fonts.
+
+## 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.
+
+An alternative is to turn off the use of Roboto from Google Fonts and
+then [configure custom fonts to use], 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-builtin/mkdocs.yml

@@ -0,0 +1,44 @@
+# Copyright (c) 2016-2023 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: Using built-in browser fonts
+site_author: Alex Voss
+
+# Copyright
+copyright: Copyright &copy; 2016 - 2023 Alex Voss and Martin Donath
+
+# Theme
+theme:
+  name: material
+  font: false
+
+# Markdown Extensions
+# (needed for this example, not for turning off Google Fonts)
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+

examples/fonts-builtin/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-custom/docs/README.md

@@ -0,0 +1,167 @@
+# Using a custom font
+
+This example uses the Noto Serif and Noto Mono font families to show
+how custom fonts can be used. These families were chosen because the 
+[Noto fonts are well documented] and they are available under the 
+[Open Font License].
+
+[Noto fonts are well documented]: https://notofonts.github.io/noto-docs/
+[Open Font License]: https://scripts.sil.org/ofl
+
+In this example, the fonts are loaded from a CDN (that is not Google)
+to keep the example itself small and allow you to use it as a template
+for your own site, without assuming what fonts you might want to use.
+We also describe how to use custom fonts that are hosted on your own
+server, see below.
+
+Here we have some text in:
+
+- Noto Serif
+- **Noto Serif bold**
+- *Noto Serif italic*
+- __*Noto Serif bold italic*__
+- `Noto Mono`
+- __`Noto Mono bold`__ 
+
+!!! tip "Privacy Plugin"
+
+    Before you consider the examples below, you should know that loading fonts
+    or other assets from a CDN may bring you into non-compliance with data
+    protection legislation such as the GDPR in the EU. You can read more about
+    this in the [ensuring data privacy] section of the documentation.
+
+    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 together with your documentation.  No need for a custom stylesheet.
+
+[ensuring data privacy]: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy
+[privacy plugin]: https://squidfunk.github.io/mkdocs-material/plugins/privacy/
+
+## How it works
+
+In `mkdocs.yml`, turn off the auto-loading of fonts from Google Fonts
+and add an extra CSS stylesheet to configure your custom fonts.
+
+```yaml
+theme:
+  font: false
+
+extra_css:
+  - assets/stylesheets/extra.css
+```
+
+Then, [configure custom fonts] hosted either on a CDN or on your own
+server, depending on your needs. We demonstrate this here with the 
+Noto Sans and Noto Mono font families.
+
+[configure custom fonts]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/#additional-fonts
+
+### Using a CDN's CSS
+
+If you are using a CDN to load your fonts, you may want to use CSS
+that the operators of the CDN are providing for defining the font
+faces, instead of writing your own. You still need to configure the
+fonts for Material to use, though:
+
+=== "`mkdocs.yml`"
+
+    ```yaml
+    extra_css:
+      - https://fonts.cdnfonts.com/css/noto-serif
+      - https://fonts.cdnfonts.com/css/noto-mono
+      - assets/stylesheets/extra.css
+    ```
+
+=== "`extra.css`"
+
+    ```css
+    :root {
+      --md-text-font: "Noto Serif";
+      --md-code-font: "Noto Mono";
+    }
+    ```
+
+### Hosting on your own site
+
+The code for hosting the fonts yourself as part of your site, looks
+very similar to the previous example that used a CDN. You need to
+write your own font face definitions and point the browser 
+to the files located on your own server, e.g., in
+`docs/assets/fonts`:
+
+=== "`mkdocs.yml`"
+
+    ```yaml
+    extra_css:
+      - assets/stylesheets/extra.css
+    ```
+
+=== "`extra.css`"
+
+    ```css
+    @font-face {
+      font-family: "Noto Serif"; 
+      font-weight: normal; 
+      font-style: normal;
+      src: url("../fonts/NotoSerif-Regular.otf");
+    }
+
+    @font-face {
+      font-family: "Noto Serif"; 
+      font-weight: bold; 
+      font-style: normal;
+      src: url("../fonts/NotoSerif-Bold.otf");
+
+    }
+
+    @font-face {
+      font-family: "Noto Serif"; 
+      font-weight: normal; 
+      font-style: italic;
+      src: url("../fonts/NotoSerif-Italic.otf");
+
+    }
+
+    @font-face {
+      font-family: "Noto Mono"; 
+      font-weight: normal; 
+      font-style: normal;
+      src: url("../fonts/NotoSansMono-Regular.otf");
+
+    }
+
+    @font-face {
+      font-family: "Noto Mono"; 
+      font-weight: bold; 
+      font-style: normal;
+      src: url("../fonts/NotoSansMono-Bold.otf");
+    }
+
+    :root {
+      --md-text-font: "Noto Serif";
+      --md-code-font: "Noto Mono";
+    }
+    ```
+
+
+## (Dis-)Advantages
+
+If you are loading the fonts from a CDN as in this example, you are still not
+limiting traffic to only your website. To do that you would need to host the
+fonts as part of your site as described above. We include the CDN example here
+because you may have other reasons to use a CDN other than Google Fonts.
+
+Try not to use too many different fonts as that will slow down your page load
+and rendering times.
+
+Compared to using built-in browser fonts only, you have more control over the
+look of your site.
+
+## Alternatives
+
+Alternatively, you can simply [use built-in browser fonts] but that
+does mean giving up some control over the look of your site.
+
+[use built-in browser fonts]: ../fonts-builtin

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

@@ -0,0 +1,43 @@
+@font-face {
+  font-family: "Noto Serif";
+  font-weight: normal;
+  font-style: normal;
+  src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSerif/unhinted/otf/NotoSerif-Regular.otf");
+}
+
+@font-face {
+  font-family: "Noto Serif";
+  font-weight: bold;
+  font-style: normal;
+  src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSerif/unhinted/otf/NotoSerif-Bold.otf");
+
+}
+
+@font-face {
+  font-family: "Noto Serif";
+  font-weight: normal;
+  font-style: italic;
+  src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSerif/unhinted/otf/NotoSerif-Italic.otf");
+
+}
+
+@font-face {
+  font-family: "Noto Mono";
+  font-weight: normal;
+  font-style: normal;
+  src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSansMono/unhinted/otf/NotoSansMono-Regular.otf");
+
+}
+
+@font-face {
+  font-family: "Noto Mono";
+  font-weight: bold;
+  font-style: normal;
+  src: url("https://cdn.jsdelivr.net/gh/notofonts/notofonts.github.io/fonts/NotoSansMono/unhinted/otf/NotoSansMono-Bold.otf");
+}
+
+:root {
+  --md-text-font: "Noto Serif";
+  --md-code-font: "Noto Mono";
+}
+

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

@@ -0,0 +1,43 @@
+@font-face {
+  font-family: "Noto Serif";
+  font-weight: normal;
+  font-style: normal;
+  src: url("../fonts/NotoSerif-Regular.otf");
+}
+
+@font-face {
+  font-family: "Noto Serif";
+  font-weight: bold;
+  font-style: normal;
+  src: url("../fonts/NotoSerif-Bold.otf");
+
+}
+
+@font-face {
+  font-family: "Noto Serif";
+  font-weight: normal;
+  font-style: italic;
+  src: url("../fonts/NotoSerif-Italic.otf");
+
+}
+
+@font-face {
+  font-family: "Noto Mono";
+  font-weight: normal;
+  font-style: normal;
+  src: url("../fonts/NotoSansMono-Regular.otf");
+
+}
+
+@font-face {
+  font-family: "Noto Mono";
+  font-weight: bold;
+  font-style: normal;
+  src: url("../fonts/NotoSansMono-Bold.otf");
+}
+
+:root {
+  --md-text-font: "Noto Serif";
+  --md-code-font: "Noto Mono";
+}
+