Blockflow

Blockflow is a fork of Scratch for building guided tutorials. Hyperbook provides two directives for embedding Blockflow: a player for playing tutorials and an editor for creating them.

Hyperbook includes a pinned Blockflow browser bundle. The CLI downloads it the first time a build uses Blockflow. Books that use either directive serve one shared local copy, so the editor and player do not depend on blockflow.openpatch.org. The VS Code extension does not include the bundle. Its preview uses the CLI's downloaded copy, or loads Blockflow from blockflow.openpatch.org until it is downloaded. Local project files and tutorial media work offline when the book is served locally; remote projects, Scratch library assets, and network extensions still need internet access. The bundled Blockflow license and source link are included with its assets.

Player

The Blockflow Player embeds a player for playing Scratch-based guided tutorials.

Player Attributes

Attribute	Description	Default
`src`	URL to the `.sb3` file	-
`width`	Width of the player	`100%`
`height`	Height of the player	`600px`
`aspectRatio`	Aspect ratio of the player container	`4/3`

::blockflow-player{src="https://hyperbook.openpatch.org/elements/platformer.sb3"}

Editor

The Blockflow Editor embeds an editor for creating Scratch-based guided tutorials. You can define tutorial steps directly in markdown, and the configuration is generated automatically at build time.

Editor Attributes

Attribute	Description	Default
`title`	Title of the tutorial	-
`src`	Path or URL to the `.sb3` Scratch project file	-
`project`	URL to a `.json` project file; when set, inline configuration is ignored	-
`width`	Width of the editor	`100%`
`height`	Height of the editor	`700px`
`aspectRatio`	Aspect ratio of the editor container	-
`allowExtensions`	Allow Scratch extensions (`true` or `false`)	`true`
`showCostumesTab`	Show or hide the Costumes/Backdrops tab (`true` or `false`)	`true`
`showSoundsTab`	Show or hide the Sounds tab (`true` or `false`)	`true`
`categories`	Comma-separated list of toolbox categories	-
`blocks-<category>`	Comma-separated list of blocks available in a category	-

Basic Usage

::::blockflow-editor{title="My Tutorial" src="./platformer.sb3"}
 
:::step{title="Welcome"}
This is the first step of the tutorial.
:::
 
:::step{title="Move the Cat"}
Use the move block to move the cat 10 steps.
:::
 
::::

Steps

Each step is defined with a :::step directive inside the editor block. Steps support the following attributes:

title: The title of the step.
image: An optional image URL for the step.
video: An optional video URL for the step.

The text content of the step is used as the step description.

::::blockflow-editor{title="Tutorial" src="./project.sb3"}
 
:::step{title="Welcome" image="./welcome.png"}
Welcome to this tutorial!
:::
 
:::step{title="Watch this" video="./demo.mp4"}
Watch the video to see how it works.
:::
 
::::

Toolbox Configuration

You can restrict which block categories and blocks are available in the editor using the categories and blocks-<category> attributes.

categories: A comma-separated list of block categories to show, e.g. "motion,events,control,operators".
blocks-<category>: A comma-separated list of block IDs available in a specific category, e.g. blocks-motion="motion_movesteps,motion_turnright".

::::blockflow-editor{title="Tutorial" src="./project.sb3" categories="motion,events,control" blocks-motion="motion_movesteps,motion_turnright,motion_turnleft"}
 
:::step{title="Step 1"}
Try using the motion blocks!
:::
 
::::

UI Configuration

allowExtensions: Whether to allow Scratch extensions. Set to "false" to disable. Defaults to true.
showCostumesTab: Whether to show the Costumes/Backdrops tab. Set to "false" to hide. Defaults to true. (Maps to costumes.enabled in the Blockflow config.)
showSoundsTab: Whether to show the Sounds tab. Set to "false" to hide. Defaults to true. (Maps to sounds.enabled in the Blockflow config.)

::::blockflow-editor{title="Tutorial" src="./project.sb3" allowExtensions="false"}
 
:::step{title="Step 1"}
Let's get started!
:::
 
::::

Project File

Instead of configuring the editor inline, you can provide a URL to a .json project file using the project attribute. This is useful when you want to reuse a configuration or manage it externally. You can use the Blockflow Generator to create a project file.

::::blockflow-editor{project="https://example.com/tutorial.json"}
::::

When project is set, all other configuration attributes (title, src, allowExtensions, categories, blocks-*) and :::step children are ignored.