Building and hosting a pattern library on github

Hologram, Github pages, and submodules (3 mins reading time)


I built a pattern library for a project I’m working on which would help developers (and me) build web pages in a consistent way, and in keeping with the University style and brand.

Pattern libraries should be evolving things. As design features evolve and bugs get fixed so the pattern library needs to change too.

I didn’t want a series of static files which have to be updated separately from the code. I wanted a dynamic pattern library, where changes to the code get reflected directly in the library.


There are various tools for building a living pattern library, but I settled on hologram because of its ease of implementation and use.

Hologram takes inline documentation in your css/less/sass files and uses that to build html files for a static pattern library. So not only do you end up with great inline documentation for developers, but you don’t have to do anything extra to build your web-based pattern library.

Even better it integrates easily into things like grunt so your pattern library gets updated every time you make a change to a file.


So, you have your static pattern library files sitting there on your laptop. Now what?

Well, of course you could copy them to a webserver and you’re done. But this is an extra step to remember to do, and as we all know web developers are a lazy bunch and love automation.

I found a really simple way of getting your pattern library on the web is to use github pages. In itself this is just another hosting option, but the great thing about github pages is that you can publish by pushing changes up to your repository.

In my case I was using a project site, which meant using a branch called gh-pages.


The simplest way of combining committing your source code and publishing to github pages in one go is to make the gh-pages branch a submodule.

That way you can tell Hologram to publish its pattern library to your gh-pages folder (a submodule). When you make code changes, commit them to your develop branch, and then push them. You can then update your submodule and push those up too.

Now you have your code updated in github, and your hologram-generated content pushed up to your gh-pages branch in one fell swoop.

How to do it

Assuming you are in your develop or master branch, you need to make a new empty branch called gh-pages…

git checkout –orphan gh-pages

Now switch back to your develop branch and add a submodule from the gh-pages branch…

git submodule add -b gh-pages [your-github-repository-url] pattern-library

This also creates a new folder in your codebase, into which Hologram can put its pattern library html files.

Now commit and push the submodule changes in the normal way.

When you make changes to the codebase and commit them, git will warn you that you need to also commit changes to the gh-pages branch. When you commit the gh-pages they will update automatically on your github page, usually after a minute or two.

One response to “Building and hosting a pattern library on github

Leave a Reply

Your email address will not be published.