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.
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 totrue. - showCostumesTab: Whether to show the Costumes/Backdrops tab. Set to
"false"to hide. Defaults totrue. (Maps tocostumes.enabledin the Blockflow config.) - showSoundsTab: Whether to show the Sounds tab. Set to
"false"to hide. Defaults totrue. (Maps tosounds.enabledin 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.