Step by step tutorials are authored in markdown and automatically converted by the editor. This page describes the format for these tutorials.

How tutorials work

A tutorial is a sequence of steps that the user follows in a limited environment. The experience is designed to reduce the complexity of using the full editor to simply guiding the user through a precise sequence of limited interactions. Tutorials are used as “ramp up” tools to teach both how the editor works and how the basics of blocks work. An editor can have as many tutorials as needed.

Each step of the tutorial has a short description, or explanation, of the activity for the step and possibly a block example. If the step includes a block example, the editor will restrict the selection of blocks from the toolbox to only those used in the example.

Tutorial tool

You can write, edit, and test a tutorial with the online Tutorial Tool. Select the MakeCode editor target that your tutorials is for and then write the tutorial. Run your tutorial to see how it will look in the editor.

Writing tutorials

  • Basics - The basics of writing a tutorial
  • Activities - Creating an activity based tutorial
  • Snippets - Types of code snippet used in tutorials for hints, sample code, etc
  • Control options - Additional options and blocks to control tutorial behavior
  • Multi-language - Tutorials for both Blocks and Code
  • Adding Resources - Including a resource section in a tutorial
  • Publish - How to publish a tutorial
  • Troubleshoot - Troubleshooting problems with a tutorial