Skip to content

MM on Windows—for mere mortals

  • Published: 2024-01-26 12:30
  • Updated: 2024-01-26 15:51

These are the steps I’m using to install, and manage my mkDocs Material installation. I’m using Chocolatey as package manager for Windows. Because I am not fluent in managing this stuff manually, on my own.

Note

My process is the result of painful trial & error. And I'm documenting this for myself, for future reference. It contains information I wish I had known before. I'm making it public to hopefully spare others a few resources. However: proceed at your own risk.

What this is, and who it’s for

I intend this to be a pointer for users, who do not have Python installed on Windows yet. Or who are looking for options. And want to evaluate the processes of others, who don’t deem themselves to be experts. I am certainly not an expert. And this is NOT a tutorial. 😃

Based on what I learned so far:

If you've already got Python installed from a different source: do not proceed. If you've got multiple Python versions installed: do not proceed. If you’re not sure: do not proceed. If you proceed anyway and get in trouble: do not ask me for support. 😉

Also: Please do not ask the mkDocs Material devs for support. Educating users about the basics of software environment maintenance is not their responsibility. They NEED to focus on improving their software.

Stack Overflow is a much more sensible choice.

Installation using Chocolatey

From Chocolatey, I install:

  • Python 3.x package
    • This is the updatable package, the others install specific versions
      • Over time, may lead to multiple versions, and conflicts therein
  • mkDocs Material package
    • This includes mkDocs as well
      • FYI: mkDocs Material is a package built on top of mkDocs, they are two different things

Very important next step:

  • I reboot, then:
  • Check the Windows environment variables
    • The environment paths should point to the Python version I just installed
    • If there’s no entry, two/more, the next steps probably won’t work
    • Because the dependencies are likely being installed for a Python version not used by mkDocs Material

If you don’t want to use further plugins: you’re done. Have fun with mkdocs Material! In case you want to use eg the Social plugin:

Installing plugins

I then using pip (Python’s package manager, installs with Python!)—from the command line, or Powershell—to install:

Plugins for mkDocs Material, and their dependencies. The social plugin depends on the CairoSVG library:

pip install CairoSVG

Plugins for mkDocs: (not mkDocs Material)

glightbox —a lightbox for image viewing

pip install mkdocs-glightbox

mkDocs Awesome Pages Plugin—more granular control over navigation

pip install mkdocs-awesome-pages-plugin

About error messages, missing libraries

In case you’re getting error messages when using mkdocs serve for the first time. Because a plugin isn’t working: don’t fret.

For one, mkdocs provides very detailed information about the missing component or library. Including pip commands for installing them.

Reboot your computer.

Python loads its resources, libraries and dependencies at Windows’ start. Since you just installed additional ones, it needs to load them first. To install plugins successfully.

If an mkDocs or mkDocs Material plugin fails installation despite installing the libraries, they were likely not loaded yet. Reboot, install the plugin again. And it should work.

Pointers for troubleshooting

Yes, these are pointers—not tutorials either. At the same time, they’re useful for further troubleshooting steps.

Which Python version does Windows use?

Easy—open a command line or Powershell:

python --version

This returns the Python version Windows defaults to. If the version number isn’t the one you were expecting:

Check the Windows environment variables

  • Navigate to Windows environment variables
    • In case of doubt: Windows search for environment >
      • “Edit the system environment variables”
  • Refer to “system variables” (the lower box)
  • Select the entry named “Path”
  • Click edit > opens a list of entries
  • Locate the Python entry
  • Please check if that folder contains Python data

My entries look like this:

  • C:\Python312
  • C:\Python312\Scripts

In case your entries look like:

  • C:\Python311
  • C:\Python311\Scripts
  • C:\Python312
  • C:\Python312\Scripts

The topmost entry should be the Python version your system defaults to. This is also the version Windows is installs plugins to.

In case you can install eg mkdocs plugins, but mkdocs Material doesn’t find them: There’s a reasonable chance for a version mismatch.