GitHub Pages For The Rest Of Us

In A web of agreements and disagreements I documented one aspect of a recent wiki migration: conversion of MediaWiki’s markup lingo, wikitext, to Github’s lingo, Github Flavored Markdown. Here I’ll describe the GitHub hosting arrangement we ended up with.

There were two ways to do it. We could use GitHub’s built-in per-repository wiki, powered by an engine called Gollum. Or we could use GitHub Pages, a general-purpose web publishing system that powers (most famously) the website for the Ruby language. The engine behind GitHub Pages, Jekyll, is also often used for blogs. If you scan the list of Jekyll sites you’ll see that a great many are software developers’ personal blogs. That’s no accident. They are the folks who most appreciate the benefits of GitHub Pages, which include:

Simple markup. You write Markdown, Jekyll converts it to HTML. Nothing prevents you from mixing in HTML, or using HTML exclusively, but the simplicity of Markdown — more accurately, GitHub Flavored Markdown — is a big draw.

No database. For simple websites and blogs, a so-called dynamic system, backed by a database, can be overkill. You have to install and maintain the database which then regulates all access to your files. Why not just create and edit plain old files, either in a simple lingo like Markdown or in full-blown HTML, then squirt them through an engine that HTMLizes the Markdown (if necessary) and flows them through a site template? People call sites made this way static sites, which I think is a bit of a misnomer. It’s a mouthful but I prefer to call them dynamically generated and statically served. I’ve built a lot of web publishing systems over the years and they all work this way. If what you’re publishing is data that naturally resides in a database then of course you’ll need to feed the site from the database. But if what you’re publishing is stuff that you write, and that most naturally lives in the filesystem, why bother?

Version control. A GitHub Pages site is just a branch in a GitHub repository associated with some special conventions. And a GitHub repository offers many powerful affordances, including an exquisitely capable system for logging, tracking, and visualizing the edits to a set of documents made by one or more people.

Collaborative editing. When more then one person edits a site, each can make a copy of the site’s pages, edit independently of others, and then ask the site’s owner to merge in the changes.

Issue tracking. Both authors and readers of the site can use GitHub to request changes and work collaboratively to resolve those requests.

You don’t have to be a programmer to appreciate these benefits. But GitHub is a programmer-friendly place. And its tools and processes are famously complex, even for programmers. If you use the tools anyway on a daily basis, GitHub Pages will feel natural. Otherwise you’ll need a brain transplant.

Which is a shame, really. All sorts of people would want to take advantage of the benefits of GitHub Pages. If it were packaged very differently, and presented as GitHub Pages For The Rest of Us, they might be able able to. The collaborative creation and management of sets of documents is a general problem that’s still poorly solved for the vast majority of information workers. Mechanisms for collaborative editing, version control, and issue tracking often don’t exist. When they do they’re typically add-on features that every content management system implements in its own way. GitHub inverts that model. Collaborative editing, version control, and issue tracking are standard capabilities that provide a foundation on which many different workflows can be built. Programmers shouldn’t be the only ones able to exploit that synergy.

In this case, though, the authors of the wiki I was migrating are programmers. We use GitHub, and we know how to take advantage of the benefits of GitHub Pages. But there was still a problem. You don’t make a wiki with GitHub Pages, you make a conventional website. And while you can use GitHub Flavored Markdown to make it, the drill involves cloning your repository to a local working directory, then installing Jekyll and using it to compile your Markdown files into their HTML counterparts which you preview and finally push to the upstream repo. It’s a programmer’s workflow. We know the drill. But just because we can work that way doesn’t mean we should. Spontaneity is one of wiki’s great strengths. See something you want to change? Just click to make the page editable and do it. The activation threshold is as low as it can possibly be, and that’s crucial for maintaining documentation. Every extra step in the process is friction that impedes the flow of edits.

So we went with the built-in-wiki. It’s easy to get started, you just click the Wiki link in the sidebar of your GitHub repository and start writing. You can even choose your markup syntax from a list that includes MediaWiki and Markdown. As we went along, though, we felt increasingly constrained by the fixed layout of the built-in wiki. Wide elements like tables and preformatted blocks of text got uncomfortably squeezed. You can create a custom sidebar but that doesn’t replace the default sidebar which lists pages alphabetically in a way that felt intrusive. And we found ourselves using Markdown in strange ways to compensate for the inability to style the wiki.

If only you could use GitHub Pages in a more interactive way, without having to install Jekyll and then compile and push every little change. Well, it turns out that you can. Sort of.

I haven’t actually run Jekyll locally so I may be mistaken, but here’s how it looks to me. Jekyll compiles your site to a local directory which becomes the cache from which it serves up the results of its Markdown-to-HTML conversion. When you push your changes to GitHub, though, the process repeats. GitHub notices when you update the repo and runs Jekyll for you in the cloud. It compiles your Markdown to a cache that it creates and uses on your behalf.

If that’s how it works, shouldn’t you be able to edit your Markdown files directly in the repository, using GitHub’s normal interface for editing and proofing? And wouldn’t that be pretty close to the experience of editing a GitHub wiki?

Yes and yes, with some caveats. Creating new pages isn’t as convenient as in the wiki. You can’t just type in [see here](New Page) and then click the rendered link to conjure that new page into existence. Jekyll requires more ceremony. You have to manually create NewPage.md (not, evidently, “New Page.md”) in your repo. And then you have to edit NewPage.md and add something like this at the top:

---
title: New Page
layout: default
---

Since conjuring new pages by name is arguably the essence of a wiki, this clearly isn’t one. But you can create a page interactively using GitHub’s normal interface. Once that’s done, you can edit and preview “New Page.md” using GitHub’s normal interface. To me the process feels more like using the built-in wiki than compiling locally with Jekyll. And it opens the door to the custom CSS and layouts that the built-in wiki precludes.

There are, alas, still more caveats. You can’t always believe the preview. Some things that look right in preview are wrong in the final rendering. And that final rendering isn’t immediate. Changes take more or less time to show up, depending (I suppose) on how busy GitHub’s cloud-based Jekyll service happens to be. So this is far from a perfect solution. If you only need something a bit more robust than your repository’s README.md file, then the built-in wiki is fine. If you’re creating a major site like ruby-lang.org then you’ll want to install and run Jekyll locally. Between those extremes, though, there’s a middle ground. You can use GitHub Pages in a cloud-based way that delivers a wiki-like editing experience with the ability to use custom CSS and layouts,

I don’t think this particular patch of middle ground will appeal widely. Maybe a hypothetical GitHub Pages For The Rest Of Us will. Or maybe Ward Cunningham’s Smallest Federated Wiki (see also http://hapgood.us/tag/federated-wiki/) will. In any case, the ideas and methods that enable software developers to work together online are ones that everyone will want to learn and apply. The more paths to understanding and mastery, the better.