How to Fix MkDocs Plugin Errors

In this tutorial, you'll learn about How to Fix MkDocs Plugin Errors. We cover key concepts, practical examples, and best practices.

An MkDocs plugin fails with "Module not found" or "Plugin 'xyz' is not installed." Plugin installation or mkdocs.yml configuration is the issue.

The Wrong Way

# Listing a plugin that is not installed
plugins:
  - search
  - macros
  - awesome-pages

If mkdocs-awesome-pages-plugin is not installed, the build fails immediately.

The Right Way

Step 1: Install the plugin

pip install mkdocs-awesome-pages-plugin
# Verify installation:
pip show mkdocs-awesome-pages-plugin

Step 2: Check plugin configuration in mkdocs.yml

plugins:
  - search
  - macros:
      verbose: true  # plugin-specific options
  - awesome-pages

Each plugin may have its own configuration schema. Check the plugin documentation for required and optional options.

Step 3: Handle plugin ordering

plugins:
  - search               # runs first
  - awesome-pages       # runs second
  - macros              # runs last

Plugin order matters — some plugins depend on content processed by earlier plugins.

Step 4: List built-in plugins explicitly

# MkDocs built-in plugins:
plugins:
  - search     # built-in, no install needed
  - mkdocs-jupyter   # third-party, must install

If the plugins key is set, built-in plugins are NOT loaded automatically. You must list them explicitly.

All 4 plugins loaded — search, macros, awesome-pages, and minify working correctly.

Prevention

• Keep a requirements.txt with all plugin packages pinned to exact versions.
• Test plugin upgrades in a branch before merging to main.
• The plugin management pattern mirrors Doda Browser's extension registry — verify compatibility before activation.

Common Mistakes with plugin error

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world MKDOCS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

plugins:
  - search
  - macros:
      enabled: false

pip install -e /path/to/my-plugin