Review requested on a Platformer Tutorial and start of a set of Course Resourses

In a nutshell.

I’d like to replicate a course and resource I’ve done for JS in - in the Make Code Arcade system. there are more details in this overview doc

It would be great to help feedback on what direction to take this and the work I’ve done so far.

Progress so far

The following elements are now ready for review

  • Step by Step Tutorials (using MakeCode system) to create that template game - Part One - Part Two
  • Template game to remix - here
  • Quick Challenge Cards for an intro session - here
  • A template for the choice of Game Patterns tutorials - sample here

Next Stages

Help Needed

User Tutorials getting complex

It would be good to have more clarity on how to create a functioning tutorial git repo - What are the minimum set of files needed for it to work - I’ve had patchy results resulting in a lot of delay.

This repo doesn’t seem to display correctly even tho’ the README seems identical to this one created with Tutorial Tool

Perhaps there is a simpler way to create small scale tutorials like the one above without creating a git repo for each one.

Course Home Page

It would be great to be able to create a course that would live or at least be able to use the similar documentation process.

I’ll be recording videos this afternoon on how to create user tutorials. If you go to you will get additional support for tutorials:

  • all .md files have a “external” icon in the explorer that provides a tutorial preview
  • if you change the language of the editor, all .md files have a globe icon to add the localized version
    I’ll review your tutorials later this afternoon.

We support having multiple tutorials in a single repo. You can add new markdown files through the explorer and route to those files.

1 Like

Hi there - this sound promising. Thanks for your help so far.

When you say add new files via the explorer. I think you mean in this way

I wasn’t sure how to navigate to this kind of edit page on #beta for the tutorials created in the tool or in Github. So I created one from scratch on the beta site, edited the and added two more md files.

The result looks good here -

But the link routing isn’t working from that first README - I’ve tried the following way

## Adding an Enemy 
### Getting Started @unplugged

This is tutorial one in a group that add game mechanics to our starter template, for more see. 

* [Part One](
* [Part Two](

These steps are part of other which you can find on the home page of this Platformer Making Course. (course link to come)

However the resulting link is

So my questions are…

  • What would be the way of linking to these sub md files ideally both relatively and with an full URI.?
  • And is this possible to do also with these tutorials living in github repos ?

You’ll definitely want to use a GitHub repository to host your tutorials. The shared projects don’t support sub-file routing (and probably never will).

I published a tutorial for micro:bit about creating tutorials; but it also applies to

As for cross linking tutorials, let me see today about streamlining this. We do turn on GitHub Pages for repositories – so every repository also has a compiled jekyll web site web site which starts with the rendered file.
From there you could link to the deep link to the tutorials. I will publish a guide about it.

1 Like

Thanks this is helpful - I’ll get there :slight_smile:
I’ve added a comment in the following video about navigating back to the editor in beta - I think this is one of my problems at the moment.

That would be great. I’ve turned on the git pages on a test directory - so would the link be something like the following?

The standalone file is at

The routed link be something like this (not working at the moment)

You need to remove the .md extension. Our routing is quite picky at the moment - I need to make it more lenient.

So your github project should be listed in the home screen of the editor, and you can simply open it again. I’ll cover that in future videos.

Hi there,
Thanks again for your help so far. I’ve created one repository with all my tutorials in it now. And I can pull that into the editor at /beta via Import on the front page.

I’m still struggling away with these links.
I am getting a lot of inconsistencies and errors.

For example I’ve created the same file in the following locations

In the explorer the preview links both work well.
The share links in explorer (not pointing to beta) (works) (doesn’t work)

I’ve also tried the following links on beta (works) (doesn’t work)

I hope using the same file in those two locations is helpful. I’ve been playing around with a lot of different links and trying to get consistent results but not managing. Also are their caching issues when using github? and Can I get around them somehow when testing.

also here’s what i mean by not working

I’ll take a look today and also look at generating a link with beta included.

The problem seems to happen when one is signed in with github. The tutorial loads correctly after signing out. Investigating.

1 Like

We’ve pushed a fix to beta. You might have to reset your editor to make it work (make sure you save all your scripts).

We used to prefer using the github token if available. We’ve changed to always try the github proxy and bail out to using the token if failed. To avoid caching issues, I would strongly recommend to create releases of your repo. MakeCode will pick the latest release.

Hi there, that makes a lot of sense - I got the impression that I was “trying too hard” somehow - like a watched kettle never boils - and that kind of explains it.

Hi there,

Sorry to bring this thread up again.
I managed to get stable links for some time but I’ve returned to them this week and they are not longer working.

Part One

Part Two

I’m hoping to use these links for an online session early next week so any help is really appreciated.


Where are your tutorial sources?

Make sure to create releases ?that have a compliant semver syntax) tog et changes picked up. Our GitHub view in MakeCode does that.

MakeCode now uses the content of the latest release, not HEAD to load the tutorial source.


I think a problem was I had all my course material in one repo. So updates were causing problems.
I’ve separated off the Make Code tutorial parts from the others and should be all good from now on.

Part one

Part Two