Jekyll logo

On a lark I decided to take up blogging again and felt that I needed a new platform. I considered Wordpress and even Drupal but decided that I didn’t want another fussy PHP and MySQL deployment on my already overloaded servers. I was looking for a system which was:

  • Fast
  • Easy to deploy
  • Low barrier to adding content
  • High automation capabilities
  • Based on new technologies that I don’t get to work with often

Jekyll

Jekyll is a great little platform made most famous by GitHub Pages for creating a static site with minimal fuss. By combining it with Grunt and Gitlab-CI we can create a developer friendly and efficient blogging platform.

Getting Started

The first thing you’re going to need is the Jekyll gem, so open up your favorite text editor and create a Gemfile in your site directory.

source "http://rubygems.org"

gem 'jekyll'
gem 'rouge'

Save the file and make sure you have bundler gem installed with gem install bundler. Once that finishes we’ll install Jekyll and its dependencies with bundle install --path vendor/bundle. This way we don’t pollute our global gems with project dependencies. Now it’s time to set Jekyll up, run bundle exec jekyll new . to create the basic directory framework.

Git Configuration

Now would be a good time to set up Git and get a base commit in. Go ahead and run git init in the site directory and then open the .gitignore in your favorite text editor. We only want to track our development materials so let’s remove the bundle cache and install directories along with our build directories.

_site
.sass-cache
.bundle
vendor

Directory Structure

The first order of business is to create a few new directories for our development assets. Run mkdir {_drafts,img,js} to create the additional folders we need. Next we’re going to move the main.scss that Jekyll created from the default css folder and into _scss with mv css/main.scss _scss/. Now we can remove the css directory because we don’t need it anymore, all of our SASS will live in _scss. In the end our directory structure should look something like the following.

.
|- .bundle
|- .git
|- .sass-cache
|- _drafts
|- _includes
|- _layouts
|- _posts
|- _sass
|- _site
|- img
|- js
|- vendor

_config.yml

The next step is to make a few changes to Jekyll’s configuration so it accomadates our automation framework. Since Jekyll copies over all the unprefixed files to the ‘_site’ folder we need to exclude our development folders and files. Additionally, we’re going to let Grunt handle watching and recompiling our SASS so we’ll ignore that directory as well. On the other hand we don’t want Jekyll to delete our compiled assets so we’ll add their destination directories to the keep_files key.

If you prefer the triple backtick code block style you’ll need to change the markdown renderer in your _config.yml from the default kramdown to redcarpet. Additionally, if we want to use fenced code blocks with kramdown instead of relying on the Liquid template tags we have to set the syntax_highlighter option under kramdown: in our config.yml. I prefer to keep my Markdown to less than 80 characters wide but with its default options kramdown inserts a <br /> tag at each newline. To prevent this we can add the hard_wrap option to the same place we added syntax_highlighter.

...
# Build settings
markdown: kramdown
kramdown:
    hard_wrap: false
    input: GFM
    syntax_highlighter: rouge
highlighter: rouge
timezone: America/New_York
encoding: utf-8
exclude:
    - 'Gemfile'
    - 'Gemfile.lock'
    - '.git'
    - '.bundle'
    - 'vendor'
    - 'js'
    - 'img'
    - '_scss'
keep_files:
    - '_site/css'
    - '_site/img'
    - '_site/js'

Next Steps

To really get this framework off the ground we need to set up Grunt to compile our SASS files, lint our JavaScript, and optimize our images. Tune in next time for Basic Automation with Grunt.

References: