mkdocstrings-dart 0.1.1
Dart handler for mkdocstrings
Requires Python: >=3.11
Keywords: dart, mkdocs, mkdocs-plugin, mkdocstrings

# mkdocstrings-dart

![License](https://img.shields.io/github/license/andrewmurphy353/mkdocstrings-dart?logo=github)

A Dart handler for [mkdocstrings](https://mkdocstrings.github.io/), bringing beautiful, automatic API documentation to Dart packages in MkDocs.

Powered by [`dartdoc_json`](https://pub.dev/packages/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

```bash
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`:

```yaml
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:

```md
# 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:

![Screenshot of rendered Dart docs using the included example](https://raw.githubusercontent.com/andrewmurphy353/mkdocstrings-dart/main/docs/assets/screenshot.png)

## Development

```bash
# 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.