github-workflow.md

GitHub Workflow for MakeCode Tutorials

Goal: Store tutorial source (markdown + images) in a public GitHub repo, convert to MakeCode format, and generate shareable URLs.

Repository Structure (Proposed)

makecode-tutorials/
├── README.md                 # Repo overview, tutorial index
├── tutorials/
│   ├── blink-led/
│   │   ├── tutorial.md       # Source markdown
│   │   ├── images/
│   │   │   └── led-grid.png
│   │   └── tutorial.json     # Generated MakeCode format
│   ├── temperature-sensor/
│   │   ├── tutorial.md
│   │   └── tutorial.json
│   └── ...
├── scripts/
│   ├── convert.py            # Markdown → MakeCode JSON
│   ├── publish.sh            # Build + commit + push
│   └── generate-url.sh       # Create shareable URL
├── templates/
│   └── basic-tutorial.md     # Starter template
└── snippets/
    └── common-blocks.json    # Reusable block patterns

Workflow Steps

1. Author Tutorial

Brian writes tutorials/my-tutorial/tutorial.md in markdown (see format-spec.md).

Add images to tutorials/my-tutorial/images/ if needed.

2. Convert to MakeCode Format

Run converter:

python3 scripts/convert.py tutorials/my-tutorial/tutorial.md

Output: tutorials/my-tutorial/tutorial.json (MakeCode-compatible)

Converter responsibilities:

• Parse markdown frontmatter
• Split into steps (by ## headings)
• Extract code blocks (blocks vs TypeScript)
• Resolve image paths → GitHub raw URLs
• Generate MakeCode JSON schema

3. Commit & Push

git add tutorials/my-tutorial/
git commit -m "Add tutorial: my-tutorial"
git push origin main

Automation option:

./scripts/publish.sh tutorials/my-tutorial/tutorial.md

→ Runs convert, commits, pushes in one step.

4. Generate Shareable URL

MakeCode supports GitHub-hosted tutorials:

https://makecode.microbit.org/#tutorial:github:USERNAME/REPO/tutorials/my-tutorial/tutorial

Script:

./scripts/generate-url.sh my-tutorial

Output:

Tutorial URL:
https://makecode.microbit.org/#tutorial:github:brian-forwardedu/makecode-tutorials/tutorials/my-tutorial/tutorial

QR Code saved to: tutorials/my-tutorial/qr-code.png

QR code generation: Use qrencode (CLI tool) for classroom handouts.

5. Share with Students

Brian can:

• Share URL directly (paste in LMS, Slack, email)
• Print QR code handouts (students scan to open)
• Embed in course materials (iframe or link)

GitHub Pages (Optional)

If we need custom hosting (e.g., for analytics, redirects, or a tutorial index page):

1. Enable GitHub Pages on main branch
2. Create index.html with tutorial list
3. Serve assets from gh-pages branch

For now: GitHub raw URLs are sufficient (MakeCode fetches JSON directly).

Repository Settings

Visibility: Public (required for MakeCode #tutorial:github:... URLs)

Branch protection: Optional (if collaborating with others)

Topics/tags: makecode, microbit, tutorials, education

License: MIT or CC-BY (Brian's choice)

Automation Enhancements (Future)

GitHub Actions CI

Trigger on push to tutorials/**/*.md:

1. Run converter
2. Validate generated JSON
3. Auto-commit tutorial.json if changed
4. Post URL as comment on PR

Workflow file: .github/workflows/convert-tutorials.yml

Pre-commit Hook

Local hook to run converter before commit:

#!/bin/bash
# .git/hooks/pre-commit
for md in tutorials/**/tutorial.md; do
  python3 scripts/convert.py "$md"
  git add "${md%.md}.json"
done

Tutorial Index Generator

Auto-generate README.md with links to all tutorials:

python3 scripts/generate-index.py > README.md

Open Questions

1. Repo name: makecode-tutorials, microbit-tutorials, or something else?
2. Public vs private: Public required for MakeCode URLs, but Brian might want private drafts.
   • Workaround: Use a private drafts/ branch, merge to main when ready.
3. Collaboration: Will others contribute tutorials? (affects branch strategy)
4. Versioning: How to handle tutorial updates? (Git tags, changelog?)

Example Publish Workflow

# Author tutorial
cd /path/to/makecode-tutorials
mkdir -p tutorials/blink-led/images
vim tutorials/blink-led/tutorial.md

# Add images
cp ~/Downloads/led-grid.png tutorials/blink-led/images/

# Convert
python3 scripts/convert.py tutorials/blink-led/tutorial.md

# Preview locally (optional - if we build a local viewer)
# open tutorials/blink-led/tutorial.json

# Commit & push
git add tutorials/blink-led/
git commit -m "Add Blink LED tutorial"
git push origin main

# Generate URL
./scripts/generate-url.sh blink-led

# Copy URL, share with students

One-liner (after publish script is built):

./scripts/publish.sh tutorials/blink-led/tutorial.md

---

Status: Workflow spec created 2026-04-12. Ready for prototyping once MakeCode schema is researched.