GitHub Classroom allows modeling repos in the same textbook and workbook idea.

GitHub Classroom as Textbook and Workbook

In the traditional tree-killing tradition of education often there is a shiny, fancy, over-priced textbook and a significantly slimmer workbook to accompany it. GitHub Classroom allows educators to create starter “assignment” repos that every student gets when they accept the invitation by clicking on the link. This covers the workbook idea. The textbook concept can be met by creating a similarly named repo that is not used as a starter. Better than a textbook, however, GitHub allows animated GIFs, links to videos, versioning, even errata tracking and contribution through issues and PRs making it the perfect digital alternative.


Imagine you completed most of a course with a given textbook but did not finish. Your workbook would match the older text. In order to finish the course you either have to get the old textbook and approval to complete the course with that one or get a new workbook to go with the new textbook.

This dilemma exists even more in the GitHub Classrooms model because changes can be continuous and ongoing. This ability to instantly update the logical textbook of course material—and have it versioned or tagged—is perhaps the single greatest advantage of using GitHub for course material. It is crucial that major and minor versioning best practices are followed to allow students working a their own pace to easily locate this information.

Web Enabled Work Books

By making the default branch gh-pages and removing the master branch for your workbook starter repos you can allow students to use the work repo for web development and just use GitHub Pages free hosting if you don’t have another method of allowing students to host their own web content. By making the starter work repo private you also hide student work from others who might otherwise just find it online. This lets students show their work to those they wish while protecting them from prying, judgmental eyes while they learn to do the development. This the same reason leaving a student’s GitHub repo for their own personal usage untouched by educational assignments makes sense as well. Potential employers and project managers should not have to wade through a bunch of school work in a candidate’s personal GitHub repo to find their real work.

Potential employers and project managers should not have to wade through a bunch of school work in a candidate’s personal GitHub repo to find their real work.


Remember content is king, not fancy formatting and style. Use only markdown and simple files for your textbook repo content, not styles and HTML. Even though it makes sense to put all the content on the gh-pages branch so that images and such can be referred from other web sites—especially if you are using animated GIFs—it is better to get students in the habit of reading GitHub repos directly.

Sticking with simple files and markdown not only allows substantive changes to be immediate and ongoing, but encourages students to become familiar with GitHub’s tags, versioning, and branching functions. Shortcuts and links can be made from top-level web content to these to help beginners.

So long as your content is digestible and well outlined you don’t need more styling than GitHub provides despite how tempted you might be to polish it.

GitHub’s Bandwidth

Another temptation is to put all the content on a CDN for all the good reasons one would do such a thing. But this is also not needed. As soon as you do you have signed up for maintaining multiple versions of your content as it changes over time. Keeping everything on GitHub benefits everyone the most in the long run, perhaps at the cost of content taking slightly longer than some might like.

GitHub’s Reliability

GitHub ain’t going anywhere. This makes it ideal for hosting educational content that might outlive any particular instructor or content creator. It is also understood by so very many, unlike a tool like Blackboard, Canvas or whatever other made-for-educational-management tool comes along.


It makes the most sense to keep textbook repo names short and memorable, prep and prep-work, for example. This can even be paired with a subdomain shortcut ( for the absolute quickest possible access from a browser box with history. For convenience you can link the headers back to one another. I prefer linking directly to the file to keep the repo listing from cluttering the top of the page.

Linking Headers

This leaves a bit longer option for the corresponding workbooks. I’ve chosen the word ‘work’ to add with a dash after the same name as the textbook repo. Students are already shortening their directory names when they clone them from GitHub.

Another consideration is what is visible in the workbook repos to students. Often—especially with beginners—you don’t want anything in there that they cannot easily figure out. They will experiment with whatever you put in there, such as starter libraries or commands. The easiest way I have found to avoid this is to create hidden directories, .bin instead of bin, .lib instead of lib. This works best on a multiuser system on which you control at least a portion of the setup so you can add these hidden locations to the relevant paths.

Checking Off Work and Reporting

The GitHub issues system fills this need perfectly. Ideally GitHub Classroom would keep all the custom labels and open issues when importing the starter repo, but it does not. This would mean having a todo issue for each specific assignment for that course.

This can be combined with the GitHub Flavored Markdown checkboxes that can be used by the student to check off sections they have completed as they go for their own reference. The SkilStak™ Prep workbook is a one example of this.

Collaborative Curriculum Authoring

Beyond just opening issues on spelling and structure of a course textbook repo others can submit additional material to the course through the normal PR process, even students. I can’t put into words how exciting this is, truly collaborative course creation. Others have attempted this with other systems, but no system is as efficient and well established as GitHub for this.

Students can submit their own clarifications to a section of the course material that makes it easier for them to understand. This puts ownership of one’s own education fully in student’s control. Rather than complain about how bad a textbook is, issues and PRs can be created and openly debated with other contributors internally and externally to arrive at a wiki-level of consensus without letting go of central course management control and direction.

This is how education materials the world over should be created. It is how they will be created. The OER movement is just the beginning and it seems GitHub is leading the way.

This is how education materials the world over should be created. It is how they will be created. The OER movement is just the beginning and it seems GitHub is leading the way. Ironically GitHub is still blocked or banned by several public and private schools who simply do not get it, at all.