Skip to content

research-notes.md

Latest commit

 

History

History
279 lines (210 loc) · 7.28 KB

research-notes.md

File metadata and controls

279 lines (210 loc) · 7.28 KB

MakeCode Tutorial Format Research

Date: 2026-04-12
Sources: Official MakeCode documentation (makecode.com)

Key Findings

✅ MakeCode Tutorials ARE Markdown

Great news: MakeCode tutorials are already written in markdown! No complex JSON conversion needed.

Tutorial Format Summary

Basic Structure

# Tutorial Title

## Step 1

Description text here...

```blocks
basic.showString("Hello!")

Step 2

More instructions...

basic.showIcon(IconNames.Heart)


#### Key Features

1. **Title:** Level 1 heading (`#`) = tutorial title
2. **Steps:** Each `##` heading = new step
3. **Code blocks:** ````blocks` for visual blocks, ````typescript` for text code
4. **Images:** Standard markdown `![alt](url)` syntax
5. **Hints:** Any content after first code block/image = hint dialog
6. **Step modifiers:** Special tags like `@showdialog`, `@showhint`

### Publishing Methods

**Three ways to share a tutorial:**

1. **GitHub URL** (recommended for us):

https://makecode.microbit.org/#tutorial:github:username/repo/path/to/tutorial

- Requires: Public GitHub repo with markdown file
- Path: Relative to repo root, **without .md extension**
- Example: `#tutorial:github:brian-forwardedu/tutorials/blink-led/tutorial`

2. **MakeCode Project** (shared project link):
- Save tutorial as a MakeCode project
- Share project URL
- Good for quick sharing, not version-controlled

3. **Built into editor** (for MakeCode maintainers):
- Not relevant for third-party tutorials

### GitHub Hosting Details

**Requirements:**
- Public repository
- Markdown file accessible via GitHub
- Images hosted in same repo (or external CDN)
- Path in URL does NOT include `.md` extension

**URL Format:**

https://makecode.microbit.org/#tutorial:github:USERNAME/REPO/PATH/TO/FILE


**Example:**
- Repo: `github.com/brian-forwardedu/makecode-tutorials`
- File: `tutorials/blink-led/tutorial.md`
- URL: `https://makecode.microbit.org/#tutorial:github:brian-forwardedu/makecode-tutorials/tutorials/blink-led/tutorial`

**Image hosting:**
- Relative paths work: `![LED](./images/led.png)`
- MakeCode resolves images from same GitHub repo
- Or use absolute URLs (external hosting)

### Step Modifiers

Special tags in step headings:

- `@showdialog` — Display step in overlay dialog, auto-skip to next
- `@showhint` — Always show hint dialog (for important messages)
- `@unplugged` — (deprecated, use `@showdialog`)
- `@fullscreen` — (deprecated, use `@showhint`)

**Example:**
```markdown
## Introduction @showdialog

Welcome to the tutorial! Click Next to begin.

![Welcome image](./images/welcome.png)

## Step 1

Now let's code...

Code Block Types

  1. Blocks (visual):

    ```blocks
basic.showString("Hello")
```
    • Renders as draggable block UI
    • Restricts toolbox to only blocks in example

  2. TypeScript (text):

    ```typescript
let x = 5
console.log(x)
```
    • Renders as code editor
    • For JavaScript/TypeScript tutorials

  3. Block configuration:

    ```blockconfig.global
scene.setBackgroundColor(7)
```
    • Customizes default block parameters in toolbox

  4. Validation:

    ```validation.local
# BlocksExistValidator
* markers: validate-exists
```
    • Checks if student completed step correctly

Hints

Automatic hints:

  • Text before first code block/image = step description (caption)
  • Text/code after first block/image = hint (click to reveal)

Explicit hint syntax:

~hint Extra info here

This is hidden until student clicks.

hint~

Extensions/Dependencies

If tutorial needs extra blocks (extensions):

```package
microturtle=github:microsoft/pxt-microturtle
```

Caching Note

⚠️ Important: MakeCode caches tutorials locally. When testing updates:

  • Use incognito/private browser window
  • Or clear browser cache
  • Otherwise old version will show

Testing Tools

MakeCode Tutorial Tool:

What This Means for Our Project

✨ Simplifications

  1. No converter needed! We can write directly in MakeCode markdown format.
  2. No JSON schema research — markdown is the schema.
  3. Direct GitHub hosting — just push markdown to public repo.
  4. No build step — MakeCode reads markdown directly.

New Workflow

Before (imagined):

Custom markdown → Converter script → MakeCode JSON → GitHub → URL

After (actual):

MakeCode markdown → GitHub → URL

That's it! MakeCode does all the work.

What We Still Need

  1. Tutorial template — Starter markdown file following MakeCode format
  2. Image management — Where to store images, how to reference them
  3. URL generator — Script to construct GitHub tutorial URLs
  4. QR code generator — For classroom handouts
  5. Publish workflow — Git commit + push automation
  6. Tutorial index — README with links to all tutorials

What We DON'T Need

  • ❌ Markdown → JSON converter
  • ❌ MakeCode schema documentation
  • ❌ Custom hosting infrastructure
  • ❌ Build pipeline

Repository Structure (Revised)

makecode-tutorials/
├── README.md                     # Tutorial index (auto-generated)
├── tutorials/
│   ├── blink-led/
│   │   ├── tutorial.md           # MakeCode markdown (source)
│   │   └── images/
│   │       └── led-grid.png
│   ├── temperature-sensor/
│   │   ├── tutorial.md
│   │   └── images/
│   └── ...
├── templates/
│   └── basic-tutorial.md         # Starter template
├── scripts/
│   ├── generate-url.sh           # Construct GitHub tutorial URL
│   ├── generate-qr.sh            # Create QR code for URL
│   ├── publish.sh                # Git commit + push
│   └── generate-index.py         # Auto-generate README index
└── .github/
    └── workflows/
        └── update-index.yml      # CI: auto-update README on push

Note: No tutorial.json files needed! Markdown is the source format.

Next Steps

  1. ✅ Update README.md and format-spec.md with actual MakeCode format
  2. ✅ Create tutorial template file
  3. ✅ Build URL generator script
  4. ✅ Build QR code generator
  5. ✅ Create example tutorial (test with real MakeCode)
  6. Choose repo name + create GitHub repo
  7. Test live tutorial URL
  8. Document gotchas and best practices

Open Questions

  1. Repo name: makecode-tutorials, microbit-tutorials, or something else?
  2. Image hosting: GitHub repo vs external CDN? (Start with GitHub)
  3. Tutorial validation: How to test locally before pushing? (Use Tutorial Tool)
  4. Accessibility: Alt text for images, screen reader support?
  5. Analytics: Track tutorial usage (visits, completions)?

Status: Research complete! Ready to update project docs and build prototypes.