ristrettolo.gy

This is one of the two repositories responsible for the site ristrettolo.gy. It's a static site hosted on Github Pages that is built with Jekyll, it contains the text of my book CoffeeScript Ristretto.

Leanpub books are written as collections of markdown files and images, with a manifest to organize everything. These are used to generate the ebooks, and there is also a feature to export a .html file. I exported the file, choosing not to wrap it in html and body tags, and also choosing to have the entire book in one file rather than one file per chapter. That file is dropped into _includes, and the exported images are dropped into the root.

The rest of this repository is set up to create a web site that includes a "speed bump" feature: When a user scrolls approximately half-way through the book, a modal dialog appears politely suggesting that the user buy the ebook. The dialog can be dismissed to continue reading.

The "speed bump" is coded in CoffeeScript and makes use of Underscore, jQuery, and jQuery SimpleModal. Because it uses the Jekyll Asset Pipeline to transpile CoffeeScript into JavaScript, building the site is a little more involved than a typical Jekyll-on-Github-Pages site.

I'm assuming that you want to try it for either of two reasons:

You're nice enough to have noticed a bug, typo, or potential improvement and want to send a pull request, or;
You're copying the setup for your own site.

Either way, here's how it works:

background reading

In a nutshell, Github Pages publishes your static site by running it through Jekyll. Since every html page is a valid Jekyll page, Github Pages looks just like a static web server. But if you set up your repo to take advantage of Jekyll's features like Liquid Templates, Github Pages will do the processing on the server side when you push to the server.

This means that any local use of Jekyll doesn't actually affect what's served from Github, it's just for your own preview and testing purposes. This matters greatly, because Github Pages is always in safe mode, meaning that it will not run plugins, at all.

Meaning, it will not convert CoffeeScript using the asset pipeline plugin or the CoffeeScript conversion plugin. Thus, we work around it.

setup

First, clone the source repository, raganwald/ristrettolo.gy to your local system (cloning ristrettolo-gy/ristrettolo-gy.github.com is not helpful). You will also need Ruby, and Bundler and you're going to run bundle install. Or, you're going to use gem install for each of the gems in the Gemfile.

If you wish to make changes and/or send me a pull request, you can stop right here. Run jekyll to process the site locally. Run jekyll --auto to automagically process the site when you edit things locally. Run jekyll --server 3210 to run a local server on your favourite port, like 3210.

hosting your own site

You can use this to host your own site on a server. Clone this repo, then modify index.md to suit your needs. If you're using Leanpub, export your book as a single .html page and put it in _includes. I renamed it coffeescript-ristretto.html, but you don't have to rename it. Just be sure to adjust the include markup accordingly. You may also want to fiddle extensively with the styles. Finally, modify speed-bump.html to taste.

When you're happy with the contents of _site, push them to your server using your favourite method of transferring the files, such as sftp.

pushing to github pages

If you want to host your own site on Github Pages, you need to have a separate repository set up (You can't use ristrettolo-gy/ristrettolo-gy.github.com, that's my site!). We'll call your copy of raganwald/ristrettolo.gy the source repo and we'll call the new one the published repo.

When you're happy with the source repo, you'll need to copy all of the files (recursively!) from source/_site into published/: assets, index.html, CNAME, the whole shebang. Then you'll need to commit and push. It's now a static site with no plugins, and Github Pages will publish it nicely for you.

You're a programmer, so you're probably already googling for a bash script to do it for you (why create when you can sit back and consume copypasta?) Here's my exact ~/.bash_profile entries, snarfed as-is from Jekyll + Plugins + Github + You:

alias build_blog="cd ~/Dropbox/sites/ristrettolo.gy.raw; jekyll;cp -r ~/Dropbox/sites/ristrettolo.gy.raw/_site/* ~/Dropbox/sites/ristrettolo-gy.github.com;cd ~/Dropbox/sites/ristrettolo-gy.github.com;git add .;git commit -am 'Latest build.';git push"
alias bb="build_blog"

the speed bump

You might not like the speed bump, or want to experiment with other ways of displaying it. The code currently supports the option of not showing the speed bump, and also the option of not "obfuscating" the second half of the book until you dismiss the speed bump.

That's it!

p.s. If your publishing gets really complex, you could use Capistrano to deploy. But a one-line bash script is all I need, so that's what I use.

credit

ristrettolo.gy was inspired by Manuel Kiessling's The Node Beginner Book.

license

The content of CoffeeScript Ristretto is Copyright (c) 2012-2013 Reginald Braithwaite, all rights reserved. The remainder of this site, including the structure, style, JavaScript, and CoffeeScript is covered by the MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.