Getting Started#

dartdoc_modern is a drop-in replacement for dart doc that generates a modern documentation site with search, dark mode, guide pages, and interactive blocks.

Install#

dart pub global activate dartdoc_modern

Quick Start#

dartdoc_modern --format jaspr --output docs-site
cd docs-site && dart pub get && jaspr serve

dartdoc_modern --format vitepress --output docs-site
cd docs-site && npm install && npx vitepress dev

That's it. Your API docs are ready with full-text search, dark mode, and sidebar navigation.

Output Formats#

dartdoc_modern supports two output formats. Both produce the same API documentation from the same source code.

Choose Jaspr if you want everything in Dart. Choose VitePress if you want the mature static-site ecosystem.

See Jaspr vs VitePress for a deeper comparison.

Workspace / Mono-repo#

For Dart workspaces with multiple packages:

dartdoc_modern --format jaspr \
  --workspace-docs \
  --exclude-packages 'example,test_utils' \
  --output docs-site

The generator reads the workspace: key from your root pubspec.yaml and builds a unified docs site with per-package navigation.

Use --exclude-packages to skip packages that don't need documentation (examples, test utilities, internal tools).

Writing Guide Pages#

Any markdown file in doc/ or docs/ becomes a guide page in the sidebar.

my_package/
  lib/
  doc/
    getting-started.md
    configuration.md
    advanced/
      custom-themes.md
      plugins.md
  pubspec.yaml

Frontmatter#

Use YAML frontmatter to control ordering and titles:

---
sidebar_position: 1
title: Configuration
---

• sidebar_position - lower numbers appear first in the sidebar. Pages without a position are sorted alphabetically after positioned ones.
• title - overrides the sidebar label. If omitted, the first # heading or the filename is used.

Subdirectories#

Subdirectories become collapsible groups in the sidebar. An index.md inside a subdirectory sets the group title and landing page.

Visibility#

To keep a guide out of the generated site, add to frontmatter:

---
internal: true
---

Internal guides stay in your repository but are excluded from generation.

Guide Features#

DartPad Embeds#

Annotate a Dart code block with dartpad to make it interactive:

```dartpad
void main() {
  print('Hello from DartPad!');
}
```

See DartPad Embeds for options like theme, run, and height control.

Mermaid Diagrams#

Use mermaid code blocks for diagrams:

```mermaid
graph LR
  A[Source] --> B[dartdoc_modern]
  B --> C[Jaspr]
  B --> D[VitePress]
```

Callouts#

Tabs#

<Tabs defaultValue="a">
  <TabItem label="Option A" value="a">
  Content for A.
  </TabItem>
  <TabItem label="Option B" value="b">
  Content for B.
  </TabItem>
</Tabs>

Auto-Linking#

Backtick references to API symbols are automatically linked to the corresponding API page. Write `MyClass` in a guide and it becomes a clickable link.

Configuration#

CLI Flags#

Key flags beyond --format and --output:

dartdoc_options.yaml#

Most options can be set in dartdoc_options.yaml at your package root. CLI flags override file settings.

dartdoc:
  categories:
    - name: Core
      markdown: doc/categories/core.md
  categoryOrder: ["Core", "Utilities"]
  exclude:
    - "internal_library"

Deployment#

VitePress#

Build and deploy the dist folder:

cd docs-site
npx vitepress build
# deploy docs-site/.vitepress/dist

Jaspr#

Build the static site with jaspr build:

cd docs-site
dart pub get
jaspr build
# deploy docs-site/build/jaspr

For subpath hosting (e.g. https://user.github.io/my-package/):

jaspr build --dart-define DOCS_BASE_PATH=/my-package

See Jaspr Deployment for GitHub Actions workflow examples and hosting guides.

dart doc vs dartdoc_modern#

Why It Builds Faster#

dart doc creates a separate HTML page for every method, property, constructor, and constant. dartdoc_modern keeps members inline on the library or type page.

• Flutter Icons class: ~2,000 constants = ~2,001 pages in dart doc, 1 page in dartdoc_modern
• Full Dart SDK: ~15,000 HTML files vs ~1,800 markdown files

Live Examples#

• Dart SDK API docs - full Dart SDK generated with dartdoc_modern