Theme not recognized¶
Error: Unrecognized theme
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.
apt-get) and Material for MkDocs through
pip, so both packages end up in different locations. MkDocs only checks its install location for themes.
Error: Permission denied
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:
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. First, ensure that you have a Python version of 3 or higher installed:
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:
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:
--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 your Python installation by installing Python with Homebrew. 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