Jekyll & ZURB

Source for your personal blog running on Jekyll and Foundation 5. Just clone and blog: create the _posts and _drafts folder.

Demo at io.evansosenko.com/jekyll-and-zurb/.

Lots of baked in features that work even if you don't want to use Foundation.

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

Version 2 is deprecated

Version 2 will remain on Jekyll 2 and Foundation 5. Only bug fixes and security patches will be accepted for this major version which will live on the v2 branch.

Version 3 is in development and will support Jekyll 3 and Foundation 6.

For a minimal Jekyll site skeleton, check out makenew/jekyll-site. While not Foundation specific, that project is designed to be flexible and easy to maintain long-term: everything you need, nothing you don't.

Bare bones Jekyll site or blog: HTML5 & CSS3 ready.

• 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.

Running Foundation by ZURB.

• Plugins for easy responsive images and YouTube videos.
• Optional pagination using Foundation.
• Includes Foundation Icon Fonts.

Asset pipeline with Jekyll::AssetsPlugin.

• Bower for asset dependency management.

Modern web libraries and patterns.

• Syntax highlighting with highlight.js.
• Load fonts with Web Font Loader.
• Load JavaScript asynchronously with HeadJS.
• Load GitHub Gists asynchronously.
• Meta data system for SEO and social media support.
• Complete favicon set from Favic-o-matic.

Analytics and social features.

• Social media button support.
• Disqus ready: set disqus: your_shortname in _config.yml.
• 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-zurb.git my-blog

run bundle && bower install && git add Gemfile.lock and create the _posts folder. Head over to the Jekyll 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 site and as a branch to pull updates from. Thus, most features are disabled by default, and only the index.html page has been created with minimal markup.

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

Demo site hosted on GitHub pages: io.evansosenko.com/jekyll-and-zurb/.

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-zurb
$ git branch -u upstream/master jekyll-and-zurb

Then add an origin and push master

$ git remote add origin [email protected]:username/my-blog.git
$ git push -u origin master

Now, the jekyll-and-zurb 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-zurb.git
$ git fetch upstream
$ git checkout -b jekyll-and-zurb 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 variables STAGING_DOMAIN and STAGING_BASEURL are set, then they will be used to set domain and 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 support). If you want to update Foundation, update the version number in bower.json.

License

This code 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.