superdeck_builder API reference

superdeck_builder is the build-time engine for SuperDeck presentations.

Most projects should run builds through superdeck_cli, for example dart run superdeck_cli:main build --watch. Use superdeck_builder directly when you need programmatic control for custom tooling, editor integrations, or another build system.

Imports

import 'dart:async';

import 'package:superdeck_builder/superdeck_builder.dart';
import 'package:superdeck_core/superdeck_core.dart'
    show ContentBlock, DeckBuildStore, DeckWorkspace;

superdeck_builder exports the builder types. DeckWorkspace and DeckBuildStore come from superdeck_core and are required by the builder constructor signatures.

DeckBuilder

DeckBuilder builds decks from Markdown by reading a workspace, parsing slides, writing build artifacts, and returning processed slides.

Constructor

DeckBuilder({
  required DeckWorkspace workspace,
  required DeckBuildStore store,
  List<DeckBuildPlugin> plugins = const [],
});

workspace

Type: DeckWorkspace

Workspace paths used to read slides.md and write .superdeck build output.

final workspace = DeckWorkspace(
  projectDir: '.',
  slidesPath: 'slides.md',
  outputDir: '.superdeck',
);

store

Type: DeckBuildStore

Build-side storage used by the builder to initialize files, read Markdown, save deck references, and save build status.

final store = DeckBuildStore(workspace: workspace);

plugins

Type: List<DeckBuildPlugin>

Optional build plugins that transform parsed ContentBlocks before build output is written. Plugin IDs must be non-empty and unique.

Methods

build()

Future<Iterable<Slide>> build()

Runs one build and returns the processed slides.

During a build, DeckBuilder:

1. Initializes the DeckBuildStore
2. Saves build status as DeckBuildPhase.building
3. Reads deck Markdown from the store
4. Parses raw slides into Slide models
5. Applies build plugins to parsed content blocks
6. Saves deck references
7. Saves build status as DeckBuildPhase.success

final slides = await builder.build();

watchAndBuild()

Stream<BuildEvent> watchAndBuild()

Runs an initial build, then watches workspace.slidesFile and rebuilds when the file changes.

The stream emits:

1. BuildStarted
2. BuildCompleted when the build succeeds
3. BuildFailed when the build throws

The stream continues watching for later file changes.

await for (final event in builder.watchAndBuild()) {
  switch (event) {
    case BuildStarted():
      print('Build started');
    case BuildCompleted(:final slides):
      print('Built ${slides.length} slides');
    case BuildFailed(:final error, :final stackTrace):
      print('Build failed: $error');
      if (stackTrace != null) {
        print(stackTrace);
      }
  }
}

Build events

BuildEvent is the sealed base type for events emitted by watchAndBuild().

BuildStarted

const BuildStarted()

Emitted before each build starts.

BuildCompleted

const BuildCompleted(List<Slide> slides)

Emitted when a build completes successfully.

BuildFailed

const BuildFailed(Object error, [StackTrace? stackTrace])

Emitted when a watched build fails. DeckBuilder also saves failure status to the build store before emitting this event.

Build plugins

DeckBuildPlugin extends the shared DeckPlugin identity and is the class-based extension point for build-time content transforms.

/// Leaves content blocks unchanged.
final class ExampleBuildPlugin extends DeckBuildPlugin {
  /// Creates an example build plugin.
  const ExampleBuildPlugin();

  @override
  String get id => 'example.build-plugin';

  @override
  FutureOr<ContentBlock> transformContentBlock(
    ContentBlock block,
    DeckBuildContext context,
  ) {
    return block;
  }
}

Build plugins run after Markdown parsing and only receive ContentBlocks. Throw DeckFormatException when a failure should point back to invalid slide content.

Errors

DeckFormatException

const DeckFormatException(
  String message,
  dynamic source,
  int offset,
)

DeckFormatException extends FormatException and is re-exported by superdeck_builder.

Minimal example

import 'package:superdeck_builder/superdeck_builder.dart';
import 'package:superdeck_core/superdeck_core.dart'
    show DeckBuildStore, DeckWorkspace;

Future<void> main() async {
  final workspace = DeckWorkspace();
  final store = DeckBuildStore(workspace: workspace);
  final builder = DeckBuilder(
    workspace: workspace,
    store: store,
    plugins: const [],
  );

  final slides = await builder.build();
  print('Built ${slides.length} slides');

  await for (final event in builder.watchAndBuild()) {
    switch (event) {
      case BuildStarted():
        print('Build started');
      case BuildCompleted(:final slides):
        print('Built ${slides.length} slides');
      case BuildFailed(:final error, :final stackTrace):
        print('Build failed: $error');
        if (stackTrace != null) {
          print(stackTrace);
        }
    }
  }
}

Public symbols documented

From packages/builder/lib/superdeck_builder.dart:

1. BuildEvent
2. BuildStarted
3. BuildCompleted
4. BuildFailed
5. DeckBuilder
6. DeckBuildPlugin
7. DeckBuildContext
8. DeckFormatException