Logodartdoc_modern
Jaspr VitePress

Package Maintainer Recipes#

Status:

  • practical maintainer guide
  • backend-neutral

Purpose:

  • show the shortest credible path from package source to deployed docs
  • keep the choice between vitepress and jaspr honest and easy

Choose A Backend#

Choose vitepress when:

  • you want the strongest static-site ecosystem
  • your team is comfortable with Node and VitePress
  • you want the lower-risk polished path today

Choose jaspr when:

  • you want a Dart-native docs app scaffold
  • you want typed generated sidebar data and Dart-side theming
  • you want to extend the docs shell without Vue or TypeScript

Honest framing:

  • vitepress = ecosystem-first
  • jaspr = Dart-first

Recipe 1: VitePress#

Generate docs:

dartdoc_modern --format vitepress --output docs-site

Preview locally:

cd docs-site
npm install
npx vitepress dev

Build for deploy:

npx vitepress build

Deploy this directory:

docs-site/.vitepress/dist

Recipe 2: Jaspr#

Generate docs:

dartdoc_modern --format jaspr --output docs-site

Prepare and build:

cd docs-site
dart pub get
dart pub global activate jaspr_cli
jaspr build --dart-define DOCS_THEME=ocean

For subpath hosting:

jaspr build \
  --dart-define DOCS_THEME=graphite \
  --dart-define DOCS_BASE_PATH=/your-repo-name

Deploy this directory:

docs-site/build/jaspr

Before You Post Or Publish#

Strongest package-wide gate:

dart run tool/task.dart validate package-release

That covers:

  • repo-wide dart analyze --fatal-infos
  • dart pub publish --dry-run
  • the full jaspr-release gate
  • the full vitepress end-to-end smoke suite

If Playwright is installed outside /tmp/pw-run, set PLAYWRIGHT_DIR first.

If You Are Evaluating The Repo Itself#

Use the local source instead of a global install:

dart run ./bin/dartdoc_modern.dart --format vitepress --output docs-site
dart run ./bin/dartdoc_modern.dart --format jaspr --output docs-site