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 Content Publishing Stack¶
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.
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.)
We use mkdocs for our publishing tool. 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.
We use the mkdocs material theme. We encourage you to learn to add custom material widgets to your content.
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.
Setting Up a Virtual Environment with Conda¶
1 2 3 4
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:
$ 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/
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: