MkDocs API AutoNav

0.4.0 verified Mon Apr 27 auth: no python

Plugin for MkDocs that automatically generates API documentation using mkdocstrings and populates the navigation tree. Version 0.4.0 requires Python >=3.9. Active development, releases occur irregularly.

pip install mkdocs-api-autonav

Common errors

error ModuleNotFoundError: No module named 'my_template' ↓

cause The module name specified in 'modules' must be importable in the Python environment where mkdocs build runs.

fix

Install the package or adjust sys.path. Ensure the module is installed in the same environment.

error ValueError: The plugins configuration has an invalid type. Expected a list, got a string. ↓

cause In mkdocs.yml, the 'modules' value is a string instead of a list.

fix

Change to proper YAML list: modules: ['mypackage'].

error The "mkdocs-api-autonav" plugin is not compatible with the "nav" configuration option. ↓

cause Mixing old 'nav' style with new plugin style configuration. The plugin expects 'modules'.

fix

Remove or update 'nav' key. Use 'modules' key instead.

Warnings

breaking Version 0.4.0 changed the configuration from 'nav' to 'modules'. Old config will be ignored silently. ↓

fix Replace 'nav' key with 'modules' in mkdocs.yml. Example: modules: ['my_package'].

gotcha The plugin generates files in the docs directory. If you have existing docs, they may be overwritten if names collide. ↓

fix Ensure generated directories (e.g., 'api') are not manually created or tracked in version control. Add them to .gitignore.

gotcha The module list must be provided as a YAML list of strings. A single string will cause a cryptic error. ↓

fix Always use list syntax: modules: ['module1', 'module2']. Avoid quoting the whole list.

deprecated Support for Python 3.8 was dropped in 0.4.0. Install on Python 3.8 will fail. ↓

fix Upgrade Python to >=3.9 or pin to mkdocs-api-autonav==0.3.x.

Quickstart

Add the plugin to your MkDocs configuration. The plugin will scan the specified modules and generate markdown pages with mkdocstrings, automatically updating the navigation.

# mkdocs.yml
plugins:
  - search
  - mkdocs-api-autonav:
      modules:
        - "my_package"

# docs/index.md
# Welcome to My Package
# Full API reference is auto-generated.