mkdocstrings-dart 0.1.0

Dart handler for mkdocstrings

mkdocstrings-dart

A Dart handler for mkdocstrings, bringing beautiful, automatic API documentation to Dart packages in MkDocs.

Powered by dartdoc_json, it extracts doc comments, signatures, parameters, return types, and source code from your Dart libraries — no extra configuration needed.

Features

• Renders classes, constructors, methods, getters/setters
• Parameter tables with names, types, and defaults
  (Parameter descriptions appear in the main method docstring)
• Return type display
• Collapsible source code with Dart syntax highlighting
• Auto-detects your package name from pubspec.yaml
• Supports both ::: package.Class and ::: Class identifiers
• Respects paths, exclude_files, and show_source options
• Modern, wide, responsive styling

Installation

pip install mkdocstrings-dart
dart pub global activate dartdoc_json

Note: dartdoc_json is required to parse Dart source. It's lightweight and uses the official Dart analyzer.

Usage

Note: When using mkdocstrings-dart alongside other handlers (e.g., the default Python handler), you must explicitly set the default handler if you want Dart to be used for unmarked ::: blocks, otherwise define the handler with each block definition.

In your mkdocs.yml:

plugins:
  - mkdocstrings:
      default_handler: dart   # <- Required if you want ::: Identifier to use Dart by default
      handlers:
        dart:
          options:
            paths: ["lib"]                # Default: ["lib"]
            show_source: true             # Show collapsible source code
            exclude_files: ["curo.dart"]  # Optional: skip barrel files

Options

Option	Type	Default	Description
paths	list[str]	["lib"]	Directories to scan for .dart files
show_source	bool	true	Show source code in a collapsible panel
exclude_files	list[str]	[]	Basenames of files to skip (e.g., barrel files)
heading_level	int	2	Starting heading level for rendered docs

Then in your Markdown files:

# Calculator API

::: <package-name>.Calculator
# or simply
::: Calculator

Rendered Example

Below is exactly how the above ::: Calculator markdown will appear in your final HTML documentation site:

Development

# Editable install
pip install -e .
dart pub global activate dartdoc_json
mkdocs serve

Roadmap

• Support for library-level overviews
• Cross-references between classes
• Better handling of generics and annotations
• Material for MkDocs theme integration tweaks

Credits

Built with inspiration from the official mkdocstrings Python handler and powered by the excellent dartdoc_json tool.

Made with :heart: for the Dart community.