Skip to content

Learning MicroPython Authoring Guide

During the COVID-19 pandemic we were forced to move many of our in-person hands on classes to use a virtual format. We wanted an easy way for our teachers and mentors to put their content on free web pages. We evaluated more than a dozen tools and we found that git, GitHub, GitHub Pages, markdown, mkdocs, and the material themes had the closest match to our needs. These tools take some time to learn, but with the latest versions of generative AI also generating markdown we are very happy we selected these open standards.

Here are the tools you need to be familiar with to contribute to our sites.

Markdown

We use Markdown for all our content. A good way to learn Markdown is to use a Markdown cheat sheet. We want you to put many images into your classes so make sure to use the image links!

GitHub for Content Management and Version Control

We use GitHub to store our content. GitHub is free for all public content and has many advanced features that allow team to work together to build and test learning content. Many of our content authors are familiar with GitHub.

GitHub Pages for Web Sites

We use GitHub Pages to publish our content to microsites. Each coding group has their own microsite and search does not currently work across the microsites (we are working on fixing this). All content should be published into a gh-deploy branch. If you change content using the web-based editor (the pencil in the upper right corner of the github page viewer - you may need to have a friend help republish the content to the GitHub Pages site.)

MkDocs for Publishing

We use mkdocs for our publishing tool. This converts our Markdown pages into HTML web sites. To deploy mkdocs you will need to have python installed on your local computer. You must run the "mkdocs gh-deploy" command every time you make changes.

Google Material User Interface Components

We use the mkdocs material theme. We encourage you to learn to add custom material widgets to your content.

CoderDojo Style Guide

We use CoderDojo style guide for our colors, icons and fonts. Please try to stay close to these guidelines so that mentors, parents, and students all know they are on a kid-safe site.

We like our lesson plans to start with an image, gif or short video clip (under 10-seconds).

Setting Up a Virtual Environment with Conda

This section is for programmers that are setting up "build" systems on their desktops to automate the mkdocs publishing process. If you are new to Python and Conda virtual environments, please ask for help! This is not as easy is it looks, especially on Windows systems.

First, follow the installation instruction on the Conda web site:

Conda Virtual Environment Shell Installation

1
2
3
4
$ conda create --name  mkdocs python=3.6
$ conda activate mkdocs
$ pip install mkdocs
$ pip install mkdocs-material

If you are also installing quizzes on your microsite you will need additional steps not included here.

Add the site dir to your .gitignore

The mkdocs process takes Markdown files and converts them to HTML. These files are put into a folder called site. However, to publish we push this folder to the gh-deploy branch. To keep the site directory from being pushed to the main branch we need to add the directory to the .gitignore file:

Contents of .gitignore 

1
2
3
site
.DS_Store
~$*

Try to avoid links to resources that are not kid-safe.

By using these standards it will enable us to reuse this content for search, recommendation and building tools that allow students to use chatbots to help them code.

Images

All images should be stored in the doc/img directory in your site. Please keep images reasonably small (under 50K) to keep the load times fast.

Make sure when you add a new content file you link it into the navigation menu. Try to keep navigation lists under 30 items. Try using nesting if your lists get too long.

Mkdocs commands

There are only four mkdocs commands. You will rarely need to use the new command.

mkdocs build

Build the MkDocs documentation. We use this to test at the nav pages all match a document. If you get error messages in the build process you work on fixing them until the build does not return any errors.

mkdocs gh-deploy

Deploy your documentation to GitHub Pages. Run this when you want to take your local changes and push them to the web site.

Here is an example of this run:

1
2
3
4
5
6
$ mkdocs gh-deploy
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /Users/dmccrea1/Documents/ws/CoderDojoTC/site 
INFO    -  Documentation built in 0.90 seconds 
INFO    -  Copying '/Users/dmccrea1/Documents/ws/CoderDojoTC/site' to 'gh-pages' branch and pushing to GitHub. 
INFO    -  Your documentation should shortly be available at: [https://CoderDojoTC.github.io/CoderDojoTC](https://CoderDojoTC.github.io/CoderDojoTC)

mkdocs new

Create a new MkDocs project. Most of our mentors will not need to do this. We will supply you with a template zip file with all the right content if you need to create a new CoderDojo microsite of your own.

mkdocs serve

Run the builtin development server and display the web site on your local computer. This is a great way to quickly check your changes since the server watches for any file changes and immediately updates the web page.

Material examples

We chose the Google Material theme because there are tens of thousands of components you can add to your pages. You can get a sample of them here:

Material Components

Embedding Videos

We strongly encourage some movement in short 10-second demos using videos.

To embed a YouTube video do the following

  1. Use the Share button
  2. Select the Embed option
  3. Copy the iFrame code and paste it into your MarkDown
  4. Add the ?rel=0 link which will only put your own related videos on the More Video when the video is done playing.

See YouTube Embed Option for Related Videos Changes for details.