write-tutorial

name	write-tutorial
description	Create a Tutorial class with interactive steps and track registration
when-to-use	When user asks to create a tutorial, interactive guide, or learning material
effort	medium

Write Tutorial

Help the user create an interactive tutorial that educates users about Datagrok platform features.

Usage

/write-tutorial [tutorial-name] [--package <package-name>] [--track <track-name>]

Instructions

1. Install the tutorials library

The package must depend on @datagrok-libraries/tutorials:

npm install @datagrok-libraries/tutorials

2. Create the Tutorial subclass

Create a TypeScript file (e.g., src/tutorials/custom-tutorial.ts) with a class extending Tutorial:

import {Tutorial} from '@datagrok-libraries/tutorials';

export class CustomTutorial extends Tutorial {
  get name(): string { return 'Custom Tutorial'; }
  get description(): string { return 'Teaches users about a feature'; }

  protected async _run(): Promise<void> {
    // Define steps using this.action() and helper methods
    // Steps are event-based and can include interactive hints
  }
}

Key points:

• Override name and description getters.
• Implement the _run method with a sequence of steps.
• Steps use the action method or helper methods that call it internally.
• Steps can include interactive hints and detailed descriptions.

3. Register the tutorial in package.ts

Add a registration function with metadata annotations:

import {CustomTutorial} from './tutorials/custom-tutorial';

//tags: tutorial
//meta.icon: images/custom-tutorial.png
//meta.name: Custom Tutorial
//meta.track: Test Track
//description: This tutorial illustrates a new feature
//output: object
export function registerTutorial() {
  return new CustomTutorial();
}

Required annotations

Annotation	Description
tags	Must include tutorial
meta.name	Display name of the tutorial
output	Must be object (returns a Tutorial instance)

Optional annotations

Annotation	Description
meta.track	Track name this tutorial belongs to. If omitted, a new track is created for the package. If an existing track name is used, the tutorial is added to that track (even from another package).
meta.icon	Path to icon relative to package root. Default icon used if absent.
description	Displayed in the tutorial UI. Empty description if absent.

4. Register a track (optional)

To define a custom track that groups tutorials:

import {Track} from '@datagrok-libraries/tutorials';

//tags: track
//help-url: https://datagrok.ai/help
//output: object
//meta.name: Test Track
export function registerTrack() {
  return new Track('Test Track', [], 'https://datagrok.ai/help');
}

Track registration annotations:

• tags: track (required)
• meta.name (required): track display name
• help-url (required): link to documentation
• output: object (required)

5. Control visibility of standard tutorials

The Tutorials package provides default tracks (e.g., Exploratory Data Analysis, Data Access). Their visibility can be controlled at the user group level via package settings.

6. Build and publish

webpack
grok publish dev

Behavior

• Ask the user for the tutorial name, description, target package, and which track it should belong to.
• Ask what interactive steps the tutorial should include.
• Generate the Tutorial subclass with _run implementation.
• Add the registration function to package.ts with correct annotations.
• If the user wants a new track, also generate the track registration function.
• Ensure the @datagrok-libraries/tutorials dependency is present in package.json.
• Remind the user that without meta.track, tutorials get their own package-specific track.
• Follow project coding conventions: no excessive comments, no curly brackets for one-line if/for, catch/else if on new lines.