Oral Qualifying Exam

by Evan Sosenko

See this and other talks at evansosenko.com.

Source for my deck running on Jekyll and deck.js.

Source for your deck running on Jekyll and deck.js. Just clone and deck.

Demo at io.evansosenko.com/jekyll-and-deck.js/.

Lots of baked in features.

If you like this, check out the sister project Jekyll & ZURB.

Version 2 is the last stable release and will remain on Jekyll 2. Only bug fixes and security patches will be accepted.

For new decks, checkout my new Bespoke.js deck skeleton powered by Brunch and awesome.

Create your deck.js deck with Jekyll.

• Basic Rake tasks with support for dev and testing modes, run rake -D for info.
• Automatically publish to GitHub pages with Travis CI.
• LiveReload support. Just run guard.
• Use Firebase to set up a remote control for your deck.
• Slide notes using Remodal.
• Includes the custom material theme: a clean responsive style to help bootstrap your deck.

Asset pipeline with Jekyll::AssetsPlugin.

• Bower for asset dependency management.
• Sass, CoffeeScript.

Modern web libraries and patterns.

• Syntax highlighting with highlight.js.
• Load fonts with Web Font Loader.
• Load JavaScript asynchronously with HeadJS.
• MathJax ready: just set mathjax: true in _config.yml.
• Meta data system for SEO and social media: see _data/meta.yml.
• Complete favicon set from Favic-o-matic.

Analytics and social features.

• Social media button support.
• Google Analytics ready: see google_analytics variable in _config.yml.
• Piwik ready: set piwik: yoursite.com/piwik/ in _config.yml (yoursite.com/piwik/ points to the piwik install root).

Quick start

You will need Ruby ≥ 2 with Bundler and Bower.

Just clone this with

$ git clone https://github.com/razor-x/jekyll-and-deck.js.git my-deck

run bundle && bower install and make your deck in index.haml. Head over to the Jekyll Docs and deck.js docs for the rest of the details.

Running off the master branch may be unstable and is not suitable for production. Only tagged releases are considered stable.

Demo site and documentation

The master branch of this project is designed to be used as a starting point for your deck and as a branch to pull updates from. Thus, most features are disabled by default, and only a minimal deck has been created.

The demo branch is a full deck that will contain real examples and documentation for the included features. That branch is automatically built and published by Travis CI.

Demo deck hosted on GitHub pages: io.evansosenko.com/jekyll-and-deck.js/.

Add future update support

If you want to merge in future updates from this project and have your own origin, set up a separate branch to track this.

$ git remote rename origin upstream
$ git branch jekyll-and-deck.js
$ git branch -u upstream/master jekyll-and-deck.js

Then add an origin and push master

$ git remote add origin git@github.com:username/my-deck.git
$ git push -u origin master

Now, the jekyll-and-deck.js branch will pull changes from this project, which you can then merge into your other branches.

If you later clone your repo you will need to create the update branch again.

$ git remote add upstream https://github.com/razor-x/jekyll-and-deck.js.git
$ git fetch upstream
$ git checkout -b jekyll-and-deck.js upstream/master

Automatic publishing to GitHub pages with Travis CI

Note: you can still use Travis CI for testing only (no deploy step): simply add SKIP_DEPLOY=true to the Travis environment.

If you are hosting at username.github.io you will need to leave the master branch empty and put your code in a different branch. The master branch otherwise functions like the gh-pages branch below.

See here for details on the different use cases.

First, make a gh-pages branch unless you are using master as discussed above,

$ git checkout --orphan gh-pages

and remove all files and folders except the .git directory.

$ git reset .
$ git clean -fdx

Then, make an initial commit with only index.html, push it, and make sure it goes live online.

$ echo "GitHub Pages placeholder" > index.html
$ git add index.html
$ git commit -m "GitHub Pages placeholder"
$ git push -u origin gh-pages
$ git checkout master

Next, install the travis gem,

$ gem install travis

create a GitHub Deploy Key, and name the private key .deploy_key. Encrypt it with

$ travis encrypt-file .deploy_key

Commit the encrypted file .deploy_key.enc and modify the before_install quoted command in .travis.yml to match the generated one.

Instead of (or in addition to) checking .deploy_key.enc into the repository, if the DEPLOY_KEY environment variable is not empty, then its value will be used to override the contents of the .deploy_key file during the build. This is useful if you need to have repository specific deploy keys (convenient when forking or maintaining a staging site as described below). Do not use actual newlines or spaces in the environment variable string; instead, [NL] will be converted to a real newline and [SP] to a real space.

Set the source branch that will be used to build the site.

$ travis env set SOURCE_BRANCH master

Other branches will still be built for testing, but only changes to the SOURCE_BRANCH will be deployed.

Finally, switch on your repo in Travis CI and push your changes.

$ git add .travis.yml
$ git commit -m "Automatic publishing to GitHub pages with Travis CI."
$ git push

Staging site

If the environment variable STAGING_URL is set, then this value will be used to set domain, baseurl, and the assets baseurl. This is useful when you want to setup a staging site on a separate development repository.

You may override the CNAME for the staging site by setting the CNAME environment variable. Set CNAME to false to remove the CNAME file on build.

Updating

The Gemfile is using pessimistic version constraints for everything, so if you don't want to wait for updates, you need to bump the versions yourself, run bundle update and commit the updated Gemfile.lock.

JavaScript library versions need to be updated in bower.json and _config.yml (for CDN).

License

The code and content for this deck is Copyright © 2015 Evan Sosenko.

This deck is built with Jekyll & deck.js which is licensed under the MIT license.

Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.