Updated troubleshooting and data privacy pages

docs/creating-your-site.md

@@ -8,7 +8,7 @@ After you've [installed][1] Material for MkDocs, you can bootstrap your project
 documentation using the `mkdocs` executable. Go to the directory where you want
 your project to be located and enter:
 
-``` sh
+```
 mkdocs new .
 ```
 

docs/customization.md

@@ -23,7 +23,7 @@ If you want to tweak some colors or change the spacing of certain elements,
 you can do this in a separate stylesheet. The easiest way is by creating a
 new stylesheet file in the `docs` directory:
 
-``` sh
+```
 mkdir docs/stylesheets
 touch docs/stylesheets/extra.css
 ```
@@ -46,7 +46,7 @@ The same is true for additional JavaScript. If you want to integrate another
 syntax highlighter or add some custom logic to your theme, create a new
 JavaScript file in the `docs` directory:
 
-``` sh
+```
 mkdir docs/javascripts
 touch docs/javascripts/extra.js
 ```
@@ -193,13 +193,13 @@ the source of the theme and recompile it.
 In order to start development on Material for MkDocs, a [Node.js][9] version of
 at least 12 is required. First, clone the repository:
 
-``` sh
+```
 git clone https://github.com/squidfunk/mkdocs-material
 ```
 
 Next, all dependencies need to be installed, which is done with:
 
-``` sh
+```
 cd mkdocs-material
 pip install -r requirements.txt
 pip install mkdocs-minify-plugin
@@ -212,13 +212,13 @@ npm install
 
 Start the Webpack watchdog with:
 
-``` sh
+```
 npm start
 ```
 
 Then, in a second session, start the MkDocs server with:
 
-```sh
+```
 mkdocs serve
 ```
 
@@ -237,7 +237,7 @@ in front of you.
 
 When you're finished making your changes, you can build the theme by invoking:
 
-``` sh
+```
 npm run build
 ```
 

docs/data-privacy.md

@@ -14,30 +14,18 @@ some third-party services that may not.
 
 ### Google Fonts
 
-Material for MkDocs makes fonts [easily configurable][2] by relying on Google
-Fonts CDN. Embedding fonts from Google is currently within a gray area as there's
-no official statement or ruling regarding GDPR compliance and the topic is still
-[actively discussed][3]. If you need to ensure GDPR compliance, you may disable
-the usage of the Google Font CDN with:
-
-``` yaml
-theme:
-  font: false
-```
-
-When Google Fonts are disabled, Material for MkDocs will default to __Helvetica
-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.
+Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
+CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily 
+disabled][3] via `mkdocs.yml`.
 
   [2]: setup/changing-the-fonts.md
-  [3]: https://github.com/google/fonts/issues/1495
-  [4]: customization.md#overriding-blocks
+  [3]: setup/changing-the-fonts.md#disabling-font-loading
 
 ### Google Analytics and Disqus
 
-Material for MkDocs comes with optional [Google Analytics][5] and [Disqus][6] 
-integrations, both of which must be enabled explicitly.
+Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5] 
+integrations, both of which must be enabled explicitly, so there's no immediate
+action if you don't use those.
 
-  [5]: getting-started.md#google-analytics
-  [6]: getting-started.md#disqus
+  [4]: setup/setting-up-site-analytics.md#google-analytics
+  [5]: setup/adding-a-comment-system.md#disqus

docs/getting-started.md

@@ -24,7 +24,7 @@ Material for MkDocs can be installed with `pip`:
 
 === "Community edition"
 
-    ``` sh
+    ```
     pip install mkdocs-material
     ```
 
@@ -74,20 +74,20 @@ want to use the very latest version:
 
 === "Community edition"
 
-    ``` sh
+    ```
     git clone https://github.com/squidfunk/mkdocs-material.git
     ```
 
 === "Sponsor edition"
 
-    ``` sh
+    ```
     git clone git@github.com:squidfunk/mkdocs-material-next.git mkdocs-material
     ```
 
 The theme will reside in the folder `mkdocs-material/material`. Note that when
 cloning from `git`, you must install all required dependencies yourself:
 
-``` sh
+```
 pip install -r mkdocs-material/requirements.txt
 ```
 

docs/troubleshooting.md

@@ -4,87 +4,12 @@ template: overrides/main.html
 
 # Troubleshooting
 
-## Inadequate permissions
-
-> Operating systems: 
-> :fontawesome-brands-apple:
-
-!!! error "Error: Permission denied"
-
-    ``` sh
-    pip install mkdocs-material
-    # => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...'  
-    # => Consider using the --user option or check the permissions.
-    ```
-
-When you're running the pre-installed version of Python on macOS, `pip` tries
-to install packages in a folder for which your user might not have the adequate
-permissions. There are three possible solutions for this:
-
-1. __Installing in a virtual environment__: Virtual environments provide an easy
-   way of encapsulation. 
-
-2. __Installing in user space__: Provide the `--user` flag to the install
-   command and `pip` will install the package in a user-site location. Note
-   that while this is not a global installation, it's still not
-
-3. __Switching to a homebrewed Python__: Upgrade your Python installation to a
-   self-contained solution by installing Python with Homebrew. This should
-   eliminate a lot of problems you could be having with `pip`.
-
-### Virtual environments
-
-If you're installing Material for MkDocs with `pip`, the easiest way to make
-sure that you end up with the correct versions and without any incompatibility
-problems between packages it to use a [virtual environment][9]. First, ensure
-that you have a Python version of 3 or higher installed:
-
-``` sh
-python --version
-```
-
-If you're good to go, create and activate a virtual environment with:
-
-```
-python -m venv venv
-source ./venv/bin/activate
-```
-
-Note that the second `venv` is the name of the folder where to create the
-virtual environment – you may choose it as you like. Your terminal should now
-print `(venv)` before the prompt and the `python` executable should be located
-inside the folder you just created.
-
-Next, install Material for MkDocs with `pip`, which will download and install
-all packages in the `venv` folder you just created, including MkDocs and its 
-dependencies:
-
-``` sh
-pip install mkdocs-material
-```
-
-Verify that MkDocs and Material for MkDocs were both installed correctly:
-
-``` sh
-mkdocs --version
-mkdocs serve --help
-```
-
-MkDocs should list `material` as an option under the `--theme` flag. When you're 
-finished working with MkDocs, you can exit the virtual environment with:
-
-```
-deactivate
-```
-
-  [9]: https://docs.python.org/3/tutorial/venv.html
- 
 ## Theme not recognized
 
-> Operating systems: 
-> :fontawesome-brands-apple: 
-> :fontawesome-brands-windows: 
-> :fontawesome-brands-linux:
+Operating systems:
+:fontawesome-brands-apple:
+:fontawesome-brands-windows:
+:fontawesome-brands-linux:
 
 !!! error "Error: Unrecognized theme"
 
@@ -100,3 +25,93 @@ If you run into this error, the most common reason is that you installed MkDocs
 through some package manager (e.g. `brew` or `apt-get`) and Material for MkDocs
 through `pip`, so both packages end up in different locations. MkDocs only
 checks its install location for themes.
+
+## Inadequate permissions
+
+Operating systems: :fontawesome-brands-apple:
+
+!!! error "Error: Permission denied"
+
+    ``` sh
+    pip install mkdocs-material
+    # => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...'  
+    # => Consider using the --user option or check the permissions.
+    ```
+
+When you're running the pre-installed version of Python on macOS, `pip` tries
+to install packages in a folder for which your user might not have the adequate
+permissions. There are three possible solutions for this, the recommended one
+of which is to use virtual environments:
+
+=== "Virtual environments"
+
+    If you're installing Material for MkDocs with `pip`, the easiest way to make
+    sure that you end up with the correct versions and without any
+    incompatibility problems between packages it to use a [virtual
+    environment][1]. First, ensure that you have a Python version of 3 or
+    higher installed:
+
+    ```
+    python --version
+    ```
+
+    If you're good to go, create and activate a virtual environment with:
+
+    ```
+    python -m venv venv
+    source ./venv/bin/activate
+    ```
+
+    Note that the second `venv` is the name of the folder where to create the
+    virtual environment – you may choose it as you like. Your terminal should
+    now print `(venv)` before the prompt and the `python` executable should be
+    located inside the folder you just created.
+
+    Next, [install Material for MkDocs][2] with `pip`, which will download and
+    install all packages in the `venv` folder you just created, including MkDocs
+    and its dependencies:
+
+    ```
+    pip install mkdocs-material
+    ```
+
+    Verify that MkDocs and Material for MkDocs were both installed correctly:
+
+    ```
+    mkdocs --version
+    mkdocs serve --help
+    ```
+
+    MkDocs should list `material` as an option under the `--theme` flag. When
+    you're finished working with MkDocs, you can exit the virtual environment
+    with:
+
+    ```
+    deactivate
+    ```
+
+=== "User space"
+
+    Provide the `--user` flag to the install command and `pip` will install the
+    package in a user-site location. While this is not a global installation,
+    it's still not isolated and may lead to problems when you use different
+    versions of Material for MkDocs in other projects:
+
+    ```
+    pip install --user mkdocs-material
+    ```
+
+=== "Upgrade Python"
+
+    Upgrade your Python installation by installing Python with [Homebrew][3].
+    This should eliminate a lot of problems you will run into with `pip`. Yet,
+    it's still not an isolated installation which may also lead to the same
+    problems as installing in user space:
+
+    ```
+    brew upgrade python
+    ```
+
+  [1]: https://docs.python.org/3/tutorial/venv.html
+  [2]: getting-started.md#with-pip
+  [3]: https://brew.sh/

docs/upgrading.md

@@ -6,13 +6,13 @@ template: overrides/main.html
 
 Upgrade to the latest version with:
 
-``` sh
+```
 pip install --upgrade mkdocs-material
 ```
 
 Inspect the currently installed version with:
 
-``` sh
+```
 pip show mkdocs-material
 ```