This is a simple to use template that can be used to prototype and test new activities for the Mozilla Learning Networks. You can see this template working live at:

http://riomozillaclub.github.io/activity-template

The idea is that each activity lives inside their own Github repository. This leads to the advantages below:

This template system uses the popular markdown text file format to store activity data. This is much easier than changing data on static HTML files and leads to much faster iteration and easier content management. We have some links for you in case you're not familiar with this file format:

• Markdown basics
• Mastering markdown

Markdown is converted at runtime to HTML by this system, so even though you write your activity instructions in a simple text file format, the result is rendered as HTML. You don't need to install anything for this to work besides having a working git version control system available on your machine.

Each github repository has its own issue tracker. Think of it as a mini bugzilla that can be used to track discussions, problems and recommendations for the repository at hand. We can use the issues system to handle all our tasks related to the testing, improvement and discussion for a given activity. MLN already makes extensive use of github issues to handle many different tasks, this is just joining the current flow.

All repositories have their own wiki system which we can use to hold extra documentation about a given task. Stuff such as advise, recomendation for extra materials or even tips about how to deal with common challenges.

The wiki can be edited online on the github portal or managed as markdown files in a special branch. You may opt to one way or the other depending on your knowledge of git and github.

Since github repos can host static web content, it makes really easy to distribute our content using them. Mostly this frees us from having to deal with a web server and all the maintenance and security that comes from it.

The instructions here will become much more clear if you have some basic knowledge of git and github. You can learn more about both at:

• Github Guides: Github provides many guides that are quick to read/watch and will explain all that you need.
• Pro GIT book: This is an awesome book but it goes a universe beyond the knowledge you need. After this book you will become a GIT deity. The book is freely available, chapters 1 and 2 will give you knowledge enough to do any task you need.

Once you decide to create a new activity, your first step is to create a new repository on Github. You can think of a repository as a project folder. All your data about your new activity will live inside that repository.

We advise you to give a meaningful name for your repository. Usually repository names are all lowercase where words are joined by dashes as in:

club-activity-challenge-of-the-chupacabra

If we all agree on a common prefix for our repository names (such as: club-activity-*) then it will be quite easy to scan Github and find all activities

After creating your new repository on Github, follow the instructions to clone it to your machine. This will make a local copy of the repository on your computer. You will work on your local independent copy and commit and push your data back to the online repository on github. This allows you to work offline and to have a safe copy of all your data.

After cloning your new repository to your computer, you will copy all the files from this repository to your new respository. The easiest way is to download a current copy from this repository using the download link on Github. This link will give you a ZIP file will all the files you need. You can also clone this repository to your computer and then copy and paste the files from one folder to the other.

Why copying files instead of forking

If you are familiar with git you may be wondering why we're advising the user to copy files from one repository to the other instead of just forking the repository into a new one. We're doing this because of two reasons. One is technical and the other semantical.

• Technical: Github only allows you to have one fork per repository so if you fork the activity-template to create your club-activity-rainbow-slurpee then you won't be able to fork it again to create another activity.
• Semantical: You fork a project when you want to contribute back to it in the form of pull requests or when you want to take a specific project in a new direction. If you want to contribute back to this template, then forking is the correct thing to do but if you're creating new activities then this is semantically different than contributing back or taking this template into a new direction.

The only location where you will change stuff in this template system is inside the data folder. You will add your images to the data/images folder and you will customize both the aside.md and the activity.md markdown files.

This template has a main content area (content from activity.md) and a little sidebar on the left side (content from aside.md). You need to customize both files to your needs. You can experiment by opening the index.html file from your local repository, changing those markdown files, and reloading the page to see how changes work.

Tweak your content until you're happy. Remember that you can keep pushing new revisions of it to your github repo so don't be afraid to experiment.

There is some magic happening on activity.md that is beyond the normal markdown syntax. First as you can see on the top of the file there is a little header:

---
title: Kraken the Code
github: riomozillaclub/activity-template
image: square-kraken.png
competencies:
    - Search
    - Credibility
---

This holds metadata about the activity and needs to hold your own content. There is also some CSS classes automagically applied to specific paragraphs. The fourth paragraph is the Lead paragraph and fifth paragraph is the Activity time paragraph. If you check out the live activity page for the template you will notice that the fourth and fifth paragraphs are different than the others.

Each first paragraph after an horizontal ruler is a time paragraph that when rendered becomes that little circle. By playing the activity.md and checking how the content and the live version interact you will learn how to use it.

Now that you have your content ready to upload you need to commit your changes to the local repository and push them to the remote repository on github. Once you push it, it will take a little bit of time for it to be available.

Rememeber to add the image files to your commit. Just adding files to the folder is not enough for them to be added to the commit and carried over. Check the Github Guides for more information about this.

Once you push your changes back to your repository, you will be able to browse it online using the public URL for the repository. For example the URL for this repository is:

http://github.com/riomozillaclub/activity-template

The URL to see the working page becomes:

http://riomozillaclub.github.io/activity-template

You can learn more about github pages on this link.

Github pages work from the gh-pages branch. New repositories come by default with a master branch. You need to create a gh-pages branch and use it to commit and push your data. If you are using master then this will not work.

We advise you to create the gh-pages, set it as the default branch on your repository settings and then delete the master branch.

This web app uses AJAX requests to fetch the markdown files asynchronously and then process them using marked.js. It then uses handlebars.js to insert the processed markdown content into pretty templates. It is also using jQuery and YAML.js to make things easier.

All the interesting code is inside the app.js file.

Since this templating system work on the client side, I don't know how well it will index and how it will affect possible SEO stuff. IMHO I dont really care about that stuff regarding this intiative because activities are meant to be linked from a curriculum page or something similar. I don't expect people to go fishing for activities on a search engine but I am probably wrong.

You can contribute back to this initiative by sending pull requests, testing this out and giving me feedback and/or sending me recommendations and asking for new features.

Please use the issues page to contact me with your need/feedback/bug.

Areas where I need help:

• CSS: there are little CSS bugs on this page. CSS/layouting was never my strong suit. I welcome fixes!
• Testing: This needs testing.