ERROR - Config value: 'theme'. Error: Unrecognised theme name:

Question

The solution to similar issues on Github about this all point to installing MkDocs or the theme with a package manager and not pip. However, I have installed both with pip.

1. Installed MkDocs with pip (not a package manager)
2. Installed n number of MkDocs themes with pip
3. updated mkdocs.yaml to add:

theme:
   name: '{name_of_theme}'

4. then

mkdocs serve

5. result

ERROR   -  Config value: 'theme'. Error: Unrecognised theme name: '{name_of_theme}'. The available installed themes are: mkdocs, readthedocs 

What am I missing?

Answer 1

In your mkdocs.yaml, use:

theme:
   name: mkdocs

or

theme:
   name: readthedocs

Essentially, the name of a theme you actually installed.

Answer 2

Had the same problem with mkdocs-material. In my case this originated from a faulty installation of the theme. From the mkdocs-material FAQ:

1. Check if mkdoc is correctly installed: mkdocs --version. You should get the version and installed path back.
2. Check if the theme is correctly installed: mkdocs serve --help. You should get a list of parameters. Check this entry if you theme name appears: -t, --theme [material|mkdocs|readthedocs] (in this case "material")

If your theme name is missing, try reinstalling it. In my case, I had used the python -m pip flag with mkdocs and needed to do the same with the theme:

python -m pip install mkdocs
python -m pip install mkdocs-material

Answer 3

It could be that you have another version of mkdocs globally installed. That was my case.

I have recently begun using nala, a wrapper for apt, the package manager for the Debian family of Linux (I'm using Pop!_OS, a variant of Ubuntu). And it has a requirement for mkdocs from the distribution's repos, which I just realized.

When I typed mkdocs in the terminal, the wrong copy would be launched - the one in /usr/bin (actually in /usr/lib/python3/dist-packages/ according to mkdocs --version) instead of the one in my virtual environment. It's curious, because the virtual environment's bin folder was supposed to have priority in the PATH.

I uninstalled nala, which removed the globally installed mkdocs, and of course that fixed the problem, but I really like nala. I reinstalled it, and after reinstallation, the problem did not return. (Which does not make much sense to me.)

Next time, I will try to deactivate my virtual environment, then reactivate it to see if it fixes the problem. Or else I could check the path for the locally installed mkdocs (from the virtual environment) with which -a mkdocs and use its full path.

Answer 4

I've never seen the yaml file with the extension ".yaml".
Have you tried changing it to ".yml", so it's "mkdocs.yml".

You can definitely install mkdocs and a theme with pip.