Blog Post

Why and how I put syllabi on GitHub

I’ve gotten some shout-outs on ProfHacker regarding posting syllabi on GitHub.

I wanted to take to my own blog to talk about my choices behind building Git repositories for each of my courses. I also want to offer a few different approaches instructors might take for using GitHub for sharing syllabi. I’ll also preview how I’m planning to use GitHub to run a course this fall (rather than just hosting the repository course materials there). I plan to detail that process in a future post, for those instructors looking to do the same.

In his questions about the practice of posting syllabi to GitHub, Mark Sample claimed that GitHub only understands plain text, and that it’s a laborious task to convert one’s syllabi into plain text form. That’s a somewhat incomplete description of GitHub, and Git itself. And because of that, putting syllabi under Git control may not be all that laborious.

It’s more accurate to say that Git/GitHub best understands any format that exists as plain text. That includes, of course, the vanilla plaintext file, .txt, but also other forms including Markdown, HTML, and so on. (Pretty much any markup and programming language is plain text; its file extension—.txt, .md, .html, etc.—only serves to cue software as to how to interpret the file. Making matters somewhat more complicated, Windows and Mac OS both hide file extensions for known file types in their respective file/folder views.) You can put Word documents and PDF files and other binary format files under Git control. But what you lose are diffs: changes represented by a particular commit from the previous commit, or between two arbitrary commits anywhere along a repository’s timeline of development. Those diffs help to confirm and illustrate the change as described in a commit message.

But I would argue that if your syllabi are not in some plaintext form, in a flat file (versus a database entry in WordPress or Blackboard or something), they really should be.

I can make that argument from my own experience. I came to rely on GitHub for my syllabi and course-website needs from frustration with the wikis I had been using to run course websites. Every semester, I would create a new instance of WikkaWiki (which is a really nice and relatively lightweight wiki, if you’re truly in need of a wiki). But then would come the inevitable copying and pasting of materials over from previous semesters. Not to mention also the problem of how to archive the old wiki (all of my past wiki-driven courses are currently inaccessible, for exactly that reason; and I’m too paranoid to just leave the things running in case an exploit should be discovered that compromises not just the wikis themselves, but my entire server that runs them).

So I considered what needs I had that wikis were filling, and whether there wasn’t some other way to address those needs while moving to something without the overhead and security issues of a full-on per-class wiki installation. I’m developing this list in retrospect, but basically:

  • Fast editing. As an instructor, it was nice that I was able to jump in and change something on the calendar or a project description at a moment’s notice, without all of the overhead of an SFTP client or whatever.
  • Open editing. It was equally great to have a system that students could edit themselves, minus things like the course policy statement (which I used access control locks in WikkaWiki to prevent).
  • Versioning. I liked the version history of individual pages that WikkaWiki provided (although if my memory serves me correctly, the version history only went about ten revisions deep).

Git and GitHub meet all three of those needs (on top of my long-standing demand to never keep a course’s materials behind some private wall or Blackboard-like roach motel). Better still, I’d meet my needs without the overhead and risks of a database-driven system (anyone who’s installed a WordPress installation has probably experienced the phrama hack and other ills). And best of all, I needed some kind of external motivation to continue improving my own skills with Git, and to expand in what I thought were some imaginative ways for using Git and GitHub.

So, here’s how I’ve approached posting course materials on GitHub, and some new ways that I intend to try out this fall already:

GitHub Syllabus Approach No. 1: Pure Markdown

The first syllabus that I shared on GitHub was for my first stab at a course called Web Application Development. I wrote that syllabus entirely in Markdown, because GitHub is smart enough to render Markdown throughout its site (although one can see the Markdown syntax by choosing the ‘raw’ link on any page that renders Markdown). GitHub goes beyond the Markdown spec maintained by John Gruber and offers its own “GitHub-flavored Markdown,” which provides some cool functionality but probably nothing that will completely change how you’d otherwise compose a syllabus in Gruber’s original Markdown syntax.

For that original Web App Dev course, in other words, the GitHub pages for the repository itself served as the course website. I usually have a site for each of my courses on my own server at, but for that course, I decided to just let the rendering of Markdown on GitHub itself serve as the course website. There was a pedagogical reason behind that choice: students in that class were expected to use Git and GitHub to coordinate their work on the Rails applications they developed. Putting the course website up on GitHub meant that students would be working with that site—or at least becoming familiar with it—from the first day of class.

GitHub Syllabus Approach No. 2: Course Websites

Subsequent syllabi that I have shared on GitHub—including those for my Standards-Based Web Design (live site, repository) and Humanizing Technology (live site, repository) courses—are the exact HTML, CSS, and JavaScript that appears on the course websites. In fact, when I go to publish those sites on my web server, I initially just clone them onto the web server from GitHub and then subsequently pull from the GitHub repository as needed. No SFTP clients to setup and run; just an SSH connection into my server that pulls from the public URL of a given repository. I’ve even set up my iPhone with a public/private key pair, so I can pull from the repository onto my web server from virtually anywhere, without the fast internet connections that a heavy administrative backend, like on WordPress, would demand.

The only catch to this approach is that you must be able to run or install Git on your web server; otherwise, you’ll be passing around .zip files and extracting them or running SFTP clients and all of that. No fun.

GitHub Syllabus Approach No. 3: GitHub Pages

A newish feature that GitHub offers are per-repository/project web pages, which enable you to serve a website at You can see these in action on projects like Homebrew or Twitter Bootstrap. Again, because almost everything in GitHub is based in some form or another on a Git repository, the pages for a particular project are just stored in a branch called gh-pages (e.g., the Twitter Bootstrap gh-pages branch). It would be possible to create a project whose main branch was called gh-pages (rather than the default branch, master) and just serve pages that way, right from GitHub’s servers. Just point students to the GitHub pages URL for the course.

This approach should be an attractive alternative for those who aren’t interested in doing purely Markdown-flavored syllabi but who also don’t have the ability to install Git on their web servers.

GitHub Syllabus Approach No. 4: GitHub Wiki

Another GitHub feature is a per-repository wiki. Again, this is just another Git repository, although like any familiar wiki, it’s easy to edit wiki pages right through the GitHub web interface. Adding the course documents to the wiki would be trivial; although keeping them in the main repository, separate from the wiki would prevent students from making changes to documents that they probably shouldn’t have access to. Still, instructors or students who want to have their own local copy of the wiki can just clone it like any other repository.

Mix and Match

I plan to run my course website for Web Application Development this fall by blending approaches 3 and 4. I’ll update this post with links when they’re ready, but the repository itself is already up, as it has been since spring semester of 2011. That’s another thing that I am eager to see over time—how my GitHub-hosted course materials change over time, and maintain their history. (I’m starting to make use of Git tags to mark the courses at different stages of development.)

For my other course, Instructional Design, I’m planning to blend approaches 2 and 4. I think.

So, Is it Worth It?

As with just about everything I write these days (from web applications to academic articles), the course websites I build are already under Git control, so adding a GitHub remote and pushing is no big deal. And as I urge my own students when I teach them Git and GitHub, the only way you’ll ever feel remotely comfortable working in the Git universe is to use Git for just about everything you write.

Towards the end of his post, Mark Sample amps up his skeptical tone and asks directly to be convinced that posting syllabi on GitHub is “worth it.” For me, it’s worth it not just so that my materials, liberally licensed as they are, are a tad more easy to get ahold of. Sharing on GitHub also changes how I write the source of my materials (whether Markdown or HTML, and starting this fall, a nice little Sassy CSS file from which the CSS of my course sites will be compiled).

Git’s original purpose is to share the contents and development history of source code (in addition to the rendered Markdown content or the GitHub pages for a project, or the wiki it provides each repository). And that makes me think a bit more about how I go about formatting my HTML. Whereas there’s nothing wrong about writing a heading this way:

<h2>Course Goals</h2>

writing this way instead:

  Course Goals

makes it easier for others (and, frankly, me) to eyeball the content and markup that I might need to change and update, or repurpose. (And of course, this is a really simple example. More complex source would be more clearly readable with this kind of attention to source formatting.) So, by posting a course website in HTML (versus plaintext or Markdown), one might do well to consider the formatting of the source to make it maximally usable to others, including those who are not wholly literate in HTML. I’m also finding myself trying to write as vanilla of HTML as possible, keeping classes and unique IDs out of the mix so as to make the HTML I write more portable for others who may wish to copy and paste my source into their own pages.

But even if you chose not to post your syllabi on GitHub, you can still keep them under Git control. I have plenty of smaller repositories that never see the light of day beyond my own network of computers. The history of a project built up through Git alone is worth your while.