Added guide for navigation configuration

docs/troubleshooting.md

@@ -0,0 +1,102 @@
+---
+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:
+
+!!! error "Error: Unrecognized theme"
+
+    ``` sh
+    mkdocs serve
+    # => INFO    -  Building documentation...
+    # => ERROR   -  Config value: 'theme'. Error: Unrecognised theme 'material'.
+    # => ...
+    # => ConfigurationError: Aborted with 1 Configuration Errors!
+    ```
+
+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.