{"id":1561,"library":"mkdocstrings","title":"mkdocstrings","description":"mkdocstrings is an MkDocs plugin that generates automatic documentation from source code, providing an alternative to Sphinx. It leverages 'handlers' (like mkdocstrings-python) to parse different language sources and render them within your MkDocs site. The current version is 1.0.3, with frequent patch releases and occasional minor/major feature releases.","status":"active","version":"1.0.3","language":"en","source_language":"en","source_url":"https://github.com/mkdocstrings/mkdocstrings","tags":["documentation","mkdocs","autodoc","code-documentation","python"],"install":[{"cmd":"pip install \"mkdocstrings[python]\"","lang":"bash","label":"Install with Python handler"},{"cmd":"pip install mkdocstrings","lang":"bash","label":"Install core only (no handler)"}],"dependencies":[{"reason":"Core dependency; mkdocstrings is an MkDocs plugin. Requires MkDocs >= 1.6 since mkdocstrings 0.29.0.","package":"mkdocs","optional":false},{"reason":"Provides Python language support; installed via `[python]` extra.","package":"mkdocstrings-python","optional":true},{"reason":"Optional dependency for advanced cross-referencing capabilities. Required mkdocs-autorefs >= 1.4 since mkdocstrings 0.28.2.","package":"mkdocs-autorefs","optional":true}],"imports":[{"note":"This is for programmatic interaction with the plugin class itself, which is rare for typical users. Most interaction is via mkdocs.yml configuration.","symbol":"MkdocstringsPlugin","correct":"from mkdocstrings.plugin import MkdocstringsPlugin"}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Awesome Project\ntheme: material\n\nplugins:\n  - mkdocstrings: # Enable the mkdocstrings plugin\n      handlers:\n        python:\n          paths: [src] # Tell the Python handler where to find your code\n\n# src/my_module.py\ndef greet(name: str) -> str:\n    \"\"\"\n    Greets a person by their name.\n\n    Parameters:\n        name: The name of the person to greet.\n\n    Returns:\n        A personalized greeting string.\n    \"\"\"\n    return f\"Hello, {name}!\"\n\n# docs/index.md\n# Welcome\n\nThis is the main documentation page.\n\n## API Reference\n\n::: src.my_module.greet\n    options:\n      show_source: false\n","lang":"yaml","description":"To quickly get started, install mkdocstrings with the Python handler. Create a `mkdocs.yml` file, add the `mkdocstrings` plugin, and configure the Python handler to point to your source code directory (e.g., `src`). Then, in your Markdown files, use the `:::` syntax to reference your Python objects. This example shows how to document a function `greet` from `src/my_module.py`."},"warnings":[{"fix":"Review the changelog for 1.0.0. Key changes include removal of `BaseHandler.name`, `BaseHandler.domain`, `BaseHandler.fallback_config`, and changes to `BaseHandler.__init__` parameters. Update your custom handler implementations accordingly.","message":"Version 1.0.0 introduced significant breaking changes to the `BaseHandler` API. If you have custom handlers or extend `mkdocstrings` programmatically, your code will likely break.","severity":"breaking","affected_versions":"< 1.0.0 (when upgrading to 1.0.0+)"},{"fix":"Consult the official documentation for the canonical import paths of public objects. Where possible, import directly from `mkdocstrings`.","message":"Importing public objects directly from submodules (e.g., `mkdocstrings.handlers.python.PythonHandler`) was deprecated in 0.28.3 and will raise errors in v1.x. Public objects should now be imported from the top-level `mkdocstrings` module.","severity":"deprecated","affected_versions":"0.28.3 - 0.x (when upgrading to 1.x)"},{"fix":"Install the appropriate handler for your language. For Python, use `pip install \"mkdocstrings[python]\"` or `pip install mkdocstrings-python`.","message":"mkdocstrings requires a language-specific 'handler' to actually parse and document code (e.g., for Python, `mkdocstrings-python`). Installing `mkdocstrings` alone is often not enough.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `mkdocstrings` is correctly listed under `plugins:` in your `mkdocs.yml`. Verify that handler-specific options (e.g., `python.paths`) point to the correct directories containing your source code.","message":"Incorrect or missing plugin configuration in `mkdocs.yml` is a common source of errors. Users often forget to list `mkdocstrings` under the `plugins:` section or misconfigure handler-specific options like `paths`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure your `mkdocs.yml` `plugins` section as follows: `plugins: - mkdocstrings - mkdocs-autorefs`.","message":"When using `mkdocstrings` with `mkdocs-autorefs`, the order of plugins in `mkdocs.yml` matters. `mkdocstrings` should generally be listed *before* `mkdocs-autorefs` to ensure that references are properly resolved.","severity":"gotcha","affected_versions":"All versions (when using both plugins)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}