A Beautiful, Minimal Publishing Platform

pieterhpieterh wrote on 24 Oct 2013 05:09


I've just published my book, Culture & Empire, using GitHub pages and reveal.js. The results are a beautiful and minimal web-based ebook. Take a look. In this article I'll explain how I made this.


Reveal.js is a framework for smoothly animated slideshows, the brainchild of Hakim El Hattab, a talented web designer. I've used it for technical presentations, and love it. Easy to learn, and great results with so little effort.

A few days ago I decided to redo the old, click-and-wait website for iMatix with something fresher. I wanted to make it interactive, informative, and yet simple. That was a simple job. You do need to know your way around a few tools:

  • Clone the reveal.js GitHub repository and make a copy for your new project.
  • Edit the index.html file until you are happy.
  • Put on the web. Go back and edit a few dozen times until you are really happy.

As you can see, http://www.imatix.com is now pretty fun. It works like a presentation, except where the visitor decides where to go. Reveal.js has a nice 2-dimensional navigation so you can go across, and down into detail.

Next, a great free place for hosting the resulting HTML. Which is, of course, GitHub.com.

GitHub Pages

I'm a solid GitHub fan. They have a record of making minimal, accurate answers to the real problems that I've encountered in my work over some years now. Their Pages service is no exception. You get a fast, free space for your HTML, backed by a git repo. There's nothing sweeter than updating a web site by using "git push".

To make a Pages website for my firm, I created a repository imatix.github.io under my firm's organization account imatix. Then I added the reveal.js website/presentation to that, pushed it, and after a short pause (a few minutes the first time, a few seconds afterwards), it appeared magically at http://imatix.github.io.

Next step is to make this show at www.imatix.com since that is the address people know. GitHub Pages lets you define a "custom domain" that does this. First, I added a file called CNAME into my repository root directory. The file has one line "imatix.com". I committed that and pushed it. Then I went to my registrar (Gandi.net) and changed my DNS zone file to point to GitHub's address, at It takes an hour or two, then updates.

Small thing: zone files are not for the amateur. Follow the guide on the GitHub Pages site.

The whole thing took me about half a day, and the results are elegant. It's especially pleasant to read through information in this way. Fast, responsive. That evening, I wondered… how about my book?

Ah, the book. It's been years in the making and I've been publishing parts of it here. However the text is more like Scottish black bun than sponge cake. Delicious, dense, and best eaten in little pieces.

So today I hacked together a simple framework for publishing full books using reveal.js and GitHub Pages. You can fork the project and easily use it to create your own online books.

A Whole Book as a Presentation? Are you Insane?

Previously, I'd already posted the text of the book as a long narrow page, showing about 450 words per page. To read, just scroll up and down with the mouse. It gets quite tiring. There are no breaks, so there's no way to stop reading and come back later.

The alternative is to download a PDF, which many people like doing. PDFs at least give you breaks, at the price of switching away from that all-important web viewpoint.

A paper book shows perhaps 200 words per page. Well, it turns out that reading 95,000 words in chunks of about 150 at a time is even easier and more enjoyable.

What makes it work particularly well is reveal.js's horizontal (chapters) and vertical (pages in a chapter) navigation that works with the keyboard as well as the mouse.

Try it, and you'll see what I mean.

Technical Details

Culture & Empire, like all my writing, starts as plain text in a markup format. I use a custom format that does a lot of cute things that are useful to me as a write, and I use a bunch of custom Perl scripts that mangle these files into anything I need.

For this project I wanted to make a template anyone could use. That meant normalizing on a standard format. Since it's GitHub I used Markdown, their standard language for cheap-and-easy text formatting.

So step one was to write a script that turns Culture & Empire into a README.md that sits in the main repository for the book. As a nice plus, this gives us one long page with all the text, for printing, or searching.

Step two was then to generate a reveal.js index.html from that. Reveal.js does support markdown, except for tables, which I needed. So I just turned the markdown into HTML, which isn't a big deal. The script that does this is tooling/build.

Step three was to break the result into pages. I split the text at roughly 100-120 words per page. Since it's so easy and fast to paginate, this doesn't really matter. A single paragraph will never break over a page.

Step four was to tune the CSS. Though reveal.js uses SASS to generate its stylesheets, I didn't have the time to learn another framework so I just hacked the stylesheet (serif.css) by hand. The changes can be backported if this project works.

Step five was to add a footer and header on pages so that as you scroll through, you see where you are. Presentations don't need that, but books do. I quickly became a JavaScript developer, writing an event handler that updates the header and footer each time the page changes. On a new chapter page I don't show a header, and on other pages I show the chapter.

Step six was to add Google analytics, just copy/paste a script from the Analytics site. As an aside: to generate the index.html file I use a simple template approach so I have a 'header' and a 'footer' that contain things like this:

    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    ga('create', '%GATRACKER%', '%GAWEBSITE%');
    ga('send', 'pageview');

Where "%GATRACKER% and %GAWEBSITE% are taken from a spec file ("book.txt") that also provides title, subtitle, author, and so on.

Making it Social

Whew! That all took about a day, which was fantastic because as a writer, there's nothing like spending a day being really productive while actually not working on the real project.

Then I realized that perhaps someone would want to comment. I reached for my toolbox and pulled out GitHub again. GitHub issues as a forum? Well, why not. It is right there and it works. So I added a little icon that sends the reader to the GitHub issue tracker for my book. And I added a first issue to welcome people. Blank pages are confusing.

Lastly, I added the GitHub ribbon. Fork me! it says.

Next Steps

I'm thinking about moving my blog to a reveal.js + GitHub Pages combination. It would need another layout, but the idea of sections (ZeroMQ, unprotocols, security,…) along the top and blog postings as pages below is nice. As full blog postings can be quite long, perhaps using the presentation style as a navigator, and separate pages for the actual content.

What do you think? Let me know on Twitter. No-one uses these commenty things any more.


Add a New Comment
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License