CoderDojo Content Authoring Guide¶
When our CoderDojo clubs were just getting started we struggled to find high-quality content that was age appropriate for our students. We learned of the CoderDojo international foundation used simple laminated Concept Cards
Our Current CoderDojoTC Content Publishing Stack¶
GitHub for Source¶
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:
1 2 3 4
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
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.
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.
There are only four mkdocs commands. You will rarely need to use the new command.
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.
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
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.
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.
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:
We strongly encourage some movement in short 10-second demos using videos.
To embed a YouTube video do the following
- Use the Share button
- Select the Embed option
- Copy the iFrame code and paste it into your MarkDown
- Add the
?rel=0link 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.