Where to place files?

[jonsnow231]

On Windows 10, I installed MkDocs and used it to make a folder following the instructions under c:/user/documents/github.

Settings I changed all worked correctly, like changing favicon, except for anything tabbed under theme would give me an error.

While in the user/documents/github folder, I downladed pip mkdocs-material, and it downloaded programfiles/python3.7, and I believe everything to lib/site-packages. But I'm not sure because there are a few material mkdoc folders there.

The same content is in my docs with material theme, but I have no idea how to change material theme. I put a favicon.png and favicon.ico in different places in the material folders, but it only removed materials default one and didn't replace. When I remove the material theme from the config, it shows up.

[kamilkrzyskow]

Hello @jonsnow231,
I'm not really sure what are you asking about, because in most cases users don't need to know where the python packages are installed, as there is no need to modify files inside. 🤔

In the minimal reproduction guide, there is an example for setting up virtual environments:

• https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/#environment

you could use it to get more control over the installed versions of the packages between projects.

---

If you have made any changes in the site-packages then for good measure do a reinstall pip install mkdocs-material --force-reinstall.
Afterwards create an MkDocs project mkdocs new newProject , cd newProject, notepad mkdocs.yml, and replace everything with:

site_name: newProject
theme:
  name: material

mkdocs serve should show a page with the Material for MkDocs theme.

If there are any errors, provide more info, screenshots, actual files giving you the error etc.

Working file: newProject.zip

---

Some other commands you could use to see different Python installation paths:
pip show mkdocs-material
python -c "import sys; print(*sys.path, sep='\n')"
python -c "import material; print(material.__file__)"

[jonsnow231]

I uninstalled and then reinstalled in the environment, and now everything seems to work except for two things. No plugins work other than search.

With:

Plugins
  - search
  - privacy

I get:

ERROR   -  Config value 'plugins': The "privacy" plugin is not installed
Aborted with 1 configuration errors!

And then with extensions, they seem to work, but I get an error whenever I put anything nested underneath.

So for example, the emoji seems to work, showing an emoji on mkdocs serve. But when I add the emoji_index (I put four spaces further than the "p" on first line, but same error whether I put 0 or 2):

  - pymdownx.emoji:
        emoji_index: !!python/name:material.extensions.emoji.twemoji 

Traceback (most recent call last):
  File "c:\users\user\documents\github\project\venv\lib\site-packages\mkdocs\livereload\__init__.py", line 193, in _build_loop
    func()
  File "c:\users\user\documents\github\project\venv\lib\site-packages\mkdocs\commands\serve.py", line 65, in builder
    config = get_config()
  File "c:\users\user\documents\github\project\venv\lib\site-packages\mkdocs\commands\serve.py", line 50, in get_config
    **kwargs,
  File "c:\users\user\documents\github\project\venv\lib\site-packages\mkdocs\config\base.py", line 373, in load_config
    cfg.load_file(fd)
  File "c:\users\user\documents\github\project\venv\lib\site-packages\mkdocs\config\defaults.py", line 185, in load_file
    self.load_dict(yaml_load(config_file, loader))
  File "c:\users\user\documents\github\project\venv\lib\site-packages\mkdocs\utils\yaml.py", line 131, in yaml_load
    f"MkDocs encountered an error parsing the configuration file: {e}"
mkdocs.exceptions.ConfigurationError: MkDocs encountered an error parsing the configuration file: while constructing a Python object
cannot find module 'material.extensions.emoji' (No module named 'material.extensions')

This is what my project folder looks like

Also, is there a list of CSS settings that can be changed for extra.css? I started one from one of the .css files I found in venv, but didn't see how to separately set headings sizes.
extra.css.txt

[alexvoss]

What version of Material for MkDocs are you using? The first two issues would be explained if you were using an older one.

There is no list of CSS attributes that can be changed because, well, it is all of them. The best way to explore what is currently being used is the browser development tools that you can find in all modern browsers. They usually allow you to immediately try out new CSS settings as well. Learning about them is time very well invested.

[kamilkrzyskow]

Both errors indicate a lack of installed mkdocs-material:

ERROR   -  Config value 'plugins': The "privacy" plugin is not installed
...
cannot find module 'material.extensions.emoji' (No module named 'material.extensions')

use pip freeze to see the list of installed packages, and redo pip install mkdocs-material inside of your virtual environment.
EDIT: As Alex mentioned the version might be the problem as well, do a pip install mkdocs-material --upgrade to make sure you're running the newest version.

Also, is there a list of CSS settings that can be changed for extra.css?

There is no list, as everything can be changed. There is a file with defined colors in the source files, similar to what you have prepared:

• https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#custom-colors
• https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss

but didn't see how to separately set headings sizes

As for changing headings you'll have to check such things yourself in the web developer tools:

So to change the size of the h2 tag you'd use a rule like:

.md-typeset h2 {
  font-size: 2rem;
}

A normal h2 selector won't work as .md-typeset h2 is more specific:

• https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity

[jonsnow231]

Thank you, the inspection makes it very easy.

For the versions in venv:

pip = 24
python = 3.7
Babel==2.14.0
certifi==2024.7.4
charset-normalizer==3.3.2
click==8.1.7
colorama==0.4.6
ghp-import==2.1.0
idna==3.7
importlib-metadata==6.7.0
Jinja2==3.1.4
Markdown==3.4.4
MarkupSafe==2.1.5
mergedeep==1.3.4
mkdocs==1.5.3
mkdocs-material==9.2.7
mkdocs-material-extensions==1.2
packaging==24.0
paginate==0.5.6
pathspec==0.11.2
platformdirs==4.0.0
Pygments==2.17.2
pymdown-extensions==10.2.1
python-dateutil==2.9.0.post0
pytz==2024.1
PyYAML==6.0.1
pyyaml_env_tag==0.1
regex==2022.10.31
requests==2.31.0
six==1.16.0
typing_extensions==4.7.1
urllib3==2.0.7
watchdog==3.0.0
zipp==3.15.0

After upgrade, the list was exactly the same.

When I tried to make a new folder elsewhere and cd to it in the same venv, it wouldn't work, said site_name was wrong.

Then I did steps 1-4 in recreating the minimal reproduction, and when I added the privacy plugin it gave me the same error:

ERROR   -  Config value 'plugins': The "privacy" plugin is not installed
Aborted with 1 configuration errors!
ERROR   -  [13:29:42] An error happened during the rebuild. The server will appear stuck until build errors are
           resolved.

So I tried adding info plugin, and it gave me:

File "C:\Program Files\Python37\lib\runpy.py", line 193, in _run_module_as_main "__main__", mod_spec) File "C:\Program Files\Python37\lib\runpy.py", line 85, in _run_code exec(code, run_globals) File "C:\Users\user\Documents\GitHub\testproject\venv\Scripts\mkdocs.exe\__main__.py", line 7, in <module> File "c:\users\user\documents\github\testproject\venv\lib\site-packages\click\core.py", line 1157, in __call__ return self.main(*args, **kwargs) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\click\core.py", line 1078, in main rv = self.invoke(ctx) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\click\core.py", line 1688, in invoke return _process_result(sub_ctx.command.invoke(sub_ctx)) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\click\core.py", line 1434, in invoke return ctx.invoke(self.callback, **ctx.params) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\click\core.py", line 783, in invoke return __callback(*args, **kwargs) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\__main__.py", line 270, in serve_command serve.serve(**kwargs) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\commands\serve.py", line 59, in serve config = get_config() File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\commands\serve.py", line 50, in get_config **kwargs, File "c:\users\\documents\github\testproject\venv\lib\site-packages\mkdocs\config\base.py", line 378, in load_config errors, warnings = cfg.validate() File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\config\base.py", line 230, in validate run_failed, run_warnings = self._validate() File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\config\base.py", line 188, in _validate self[key] = config_option.validate(value) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\config\config_options.py", line 182, in validate return self.run_validation(value) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\config\config_options.py", line 1064, in run_validation self.load_plugin_with_namespace(name, cfg) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\config\config_options.py", line 1102, in load_plugin_with_namespace return (name, self.load_plugin(name, config)) File "c:\users\user\documents\github\testproject\venv\lib\site-packages\mkdocs\config\config_options.py", line 1120, in load_plugin plugin_cls = self.installed_plugins[name].load() File "c:\users\user\documents\github\testproject\venv\lib\site-packages\importlib_metadata\__init__.py", line 209, in load module = import_module(match.group('module')) File "C:\Program Files\Python37\lib\importlib\__init__.py", line 127, in import_module return _bootstrap._gcd_import(name[level:], package, level) File "<frozen importlib._bootstrap>", line 1006, in _gcd_import File "<frozen importlib._bootstrap>", line 983, in _find_and_load File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 677, in _load_unlocked File "<frozen importlib._bootstrap_external>", line 728, in exec_module File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed File "c:\users\user\documents\github\testproject\venv\lib\site-packages\material\plugins\info\plugin.py", line 25, in <module> import requests File "c:\users\user\documents\github\testproject\venv\lib\site-packages\requests\__init__.py", line 43, in <module> import urllib3 File "c:\users\user\documents\github\testproject\venv\lib\site-packages\urllib3\__init__.py", line 42, in <module> "urllib3 v2.0 only supports OpenSSL 1.1.1+, currently " ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'OpenSSL 1.1.0h 27 Mar 2018'. See: https://github.com/urllib3/urllib3/issues/2168

I upgraded to Python 3.12.4, and I get the same errors.

[kamilkrzyskow]

mkdocs-material==9.2.7 doesn't have the privacy version of the plugin, if the pip install mkdocs-material --upgrade doesn't update it to the latest 9.5.29 then it's likely due to a very old Python installation.

So I tried adding info plugin, and it gave me:

This is highly not recommended, as the privacy plugin relies on other Python modules, so adding one module won't fix anything.
The error you get mentions ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'OpenSSL 1.1.0h 27 Mar 2018', so the Python version is too old.

I upgraded to Python 3.12.4, and I get the same errors.

Good, but have you confirmed that python --version shows the new version, and have you deleted the previous virtual environment, and created a completely new one? When installing Python packages, they use "calibrated" wheel archives for your current Python installation, so updating Python requires reinstalling most (all) of your packages.

---

You can also add a hook to check what version of the Python interpreter is run with mkdocs build:

• https://www.mkdocs.org/user-guide/configuration/#hooks

import sys
print("version", sys.version)
print("path", sys.executable)

site_name: My Docs
hooks:
  - myhook.py

[jonsnow231]

Thanks, got it working by uninstalling python completely, and reinstalling it and mkdocs-material.