037 Jekyll

05 Apr 2013

Jekyll is a blog-aware, static site generator in Ruby. In this episode, we will install jekyll, setup a new blog and do some configurations as well as importing posts from a previous Wordpress and even hosting it on Github Pages.

Download video: mp4

Sample code: Github

Version: jekyll 1.0.0.beta2

Similar episodes: 004 GIT, 015 Github, 020 Nanoc

Background on Jekyll

  1. Main website
  2. Github
  3. Wiki
  4. Jekyll with Github pages

Things to learn with Jekyll

1. install

  1. check pre-requisites:

    ruby --version
    gem --version
    
  2. we will install the beta version with the pre-requisite of rubygems:

    gem install jekyll --pre
    jekyll --version
    
  3. common commands for jekyll

    jekyll --help
    

2. new site + deploy to github pages

  1. create a new site

    mkdir github-username.github.com
    jekyll new github-username.github.com
    cd github-username.github.com
    
  2. view the blog locally in localhost:4000

    jekyll serve
    
  3. create a git repository

    git init
    git add .
    git commit -m "initial commit"
    
  4. create a new github repository in the name github-username.github.com

    git remote add origin [email protected]:username/repo.git
    git push -u origin master
    
  5. visit http://username.github.com

3. config

  1. checkout some configurations and edit file _config.yml accordingly
  2. permalinks with pretty urls that can be configured

    permalink: /:title
    
  3. maximum number of posts

    limit_posts: 1
    
  4. change destination folder name

    destination: ./_publish
    

4. new post

  1. create a new markdown file inside folder _posts with the name yyyy-mm-dd-title.md
  2. restart the jekyll server

5. import from wordpress

  1. using the wordpress plugin for jekyll export
  2. upload the zip file to your wordpress blog as a plugin
  3. activate the plugin
  4. in the wordpress blog admin, go to Tools > Export to Jekyll
  5. copy the markdown files from the _posts folder in the exported blog to the newer blog's _posts folder
  6. restart the jekyll blog with jekyll serve locally to check everything is working. if there's and error for invalid byte sequence in US-ASCII, try to reset the locale settings

    LC_CTYPE="en_US.UTF-8"
    LANG="en_US.UTF-8"
    

6. pagination

  1. refer to the pagination document
  2. edit _config.yml

    paginate: 10
    
  3. edit file index.html according to pagination

  4. solve the /page1 error with another code reference

7. plugins - sitemap generator

  1. create a folder called _plugins with a file called sitemap_generator.rb with the code contents
  2. edit the file sitemap_generator.rb with the relvant information such as URL, etc.
  3. do a jekyll serve to check sitemap.xml has been created

8. rss

  1. create a new file called feed.xml with the following code, replacing the necessary urls
  2. enable rss auto-discovery with the link tag in the default template file inside the <head> tag

    <link rel="alternate" type="application/rss+xml" title="RSS Feed for mysite.com" href="/rss.xml" />
    

9. custom domain

  1. by default, with github pages, the site will be served on username.github.com
  2. for custom domain, add a file called CNAME and put in the domain name, example build-podcast.com

More Resources on Jekyll

  1. jekyll bootstrap
  2. octopress

Build Link of this Episode

code school - Code School teaches web technologies in the comfort of your browser with video lessons, coding challenges, and screencasts.