Registry / web-framework / mkdocs-api-autonav

mkdocs-api-autonav

library0.4.0pypypiunverified

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.

web-framework

pip install mkdocs-api-autonav

github ↗package ↗

INSTALL

IMPORT

SIG · MKDOCS-API-AUTONAV

mkdocs-api-autonav

web-frameworkpythonv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.

Debug

Known issues

breakingVersion 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'].

affects: <=0.3.x

gotchaThe 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.

affects: all

gotchaThe 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.

affects: all

deprecatedSupport 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.

affects: <0.4.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'my_template'

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.

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

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

fix

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

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

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

fix

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

Upgrade

Version history

0.4.0latest on PyPI · released Sep 9, 2025

Audit

Dependencies

mkdocsrequiredCore framework required.

mkdocstringsrequiredRequired for API doc generation.

Agent activity

3 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/tlambert03/mkdocs-api-autonav ↗

packagehttps://pypi.org/project/mkdocs-api-autonav/ ↗