Creating a Tutorial with Extension

I am working through how to create my own tutorials, specifically tutorials for the Circuit Playground Express.

I am wondering how I can load a tutorial with the Servo Extension and create tutorials around that. I haven’t been able to find documentation on how to do that. Is it possible?

I’m working on a similar project myself, but I’m using the BitBot extension. By loading the extension into my project before exporting it to GitHub, I’ve at least made the BitBot blocks accessible when the tutorial starts. The next obstacle is making the BitBot extension blocks render in the tips, which I haven’t managed to succed with yet. I thought perhaps I could use images as a workaround, but so far I haven’t succeded in making images display in the hints either. I’ve been trying to follow the instructions in the documentation for the tutorial tool, but it doesn’t seem to work.

This is possible! The thing you’re looking for is the package snippet. You’ll want something like this at the bottom of your tutorial markdown file:

```package
bitbot=github:4tronix/BitBot
```

Or the actual path to the BitBot extension, if that’s incorrect, haha. We do have docs on it here: https://makecode.com/writing-docs/snippets but it does seem pretty inconvenient that it’s not linked anywhere in the Writing Tutorials page–is there somewhere specific you guys were looking that would be useful to add this link, aside from that top-level Tutorials summary?

1 Like

I was looking in the “Adding Resources” section that’s linked from this page: https://makecode.com/writing-docs/tutorials
In fact, I’ve previously only been looking in the documents linked from the page above as I thought those links contained all there was to know about tutorials. I just made that assumption because that’s the page the “Tutorial Docs” button in the top left corner of the tutorial tool page links to.

1 Like

That makes complete sense! I’m modifying our docs to link to this file from the main tutorial page, and also possibly from the Adding Resources subpage as well. Thank you so much for your feedback!

2 Likes

I would agree. I think it would be helpful to include within the tutorials page.

I don’t know how much demand there would be for them, but I would really appreciate a video tutorial demoing how to create a tutorial, especially highlighting things like including “packages.” I think it would be really helpful to develop my own tutorials for students but I am finding the learning curve a little beyond the time I have to devote to it.

2 Likes

@shakao Awesome! Thanks! :slight_smile:

1 Like

The package snippet worked like a treat!
The blocks render perfectly!
You even got the link to BitBot on GitHub right.
Thank you SO very much! You just made my life a whole lot easier.

1 Like

Awesome, thanks so much for the feedback! You’ve probably seen this already, but just in case, Peli has a video on tutorial basics and Github hosting here: https://www.youtube.com/watch?v=R-kY-dQXZvA

But it definitely seems like something that covers the markdown in more detail would be useful as well. I’ll let the team know and we’ll see what we can do!

2 Likes

Yes! I found that video shortly after I made my previous post. I meant to comeback and share, but it slipped my mind. Thank you for following up. I appreciate it.

The video was very helpful with setting up the GitHub side of things, but as you said, it would be helpful to take a deeper dive into the markdown options. For example, I tried following the documentation for how to insert an image, but I haven’t been able get it to work as it is written. I dug into the example tutorial though and saw there was a different way to do it using a direct link from GitHub which worked.

1 Like

Yup, that’s the video that got me started. A video that goes more into detail would be very welcome indeed. :slight_smile: There doesn’t seem to be a lot of videos covering this stuff around.

1 Like