How to setup a blog with Jekyll

November 20th, 2013 4 minute read

Writing is rewriting. Writing and editing come in iterative progression. If you want to focus on writing, Jekyll is a good solution to keep a blog. Jekyll is “an open-source simple static site generator”. What that means is Jekyll converts plain text files from a computer into a website or blog. If you like writing in Markdown, you will like a solution like Jekyll for blogging. Using Jekyll has some advantages over more complex systems. It is built for writing. You don’t need to log anywhere to access and change your content although you can also edit it through a GitHub account. But you can just as well write a text on your computer and let Git mirrors it and build it, either on GitHub or on your own self hosted server. Git “is a free and open source distributed version control system”. Pushing revisions to Git is a convenient way to publish and review notes. Since Git keeps track of all changes, you can revert to any previous version at anytime. Using GitHub pages is free. Web hosting, traffic pikes, databases or downtimes are no longer a concern once your site is set up. Serving static files is fast. Another major advantage is security: there is no entry point to hack.

Quick start

Requirements: → Ruby


→ Linux, Unix, or Mac OS X1


Install Jekyll on Mac OS X

Install Xcode from the AppStore:

First, make sure you have Xcode Command Line Tools installed.

Using the Terminal located in Applications/Utilities/Terminal

xcode-select --install

You can now use the command line to run the rest of the installation commands.

First install Homebrew:

/usr/bin/ruby -e "$(curl -fsSL"

Homebrew is useful because it will manage the various packages installations. If you have Homebrew already, check for updates.

brew update

Next, you need install Ruby. Your system might already have this, but we’ll be getting the latest version.

brew install rbenv ruby-build

# Add rbenv to bash so that it loads every time you open a terminal
echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile
source ~/.bash_profile

# Install Ruby (specific version)
rbenv install 2.5.1
rbenv global 2.5.1
ruby -v

Now, at last, you are ready to install Jekyll

sudo gem install jekyll
brew install ruby

Using the command line:

$ gem install jekyll
~ $ jekyll new my-awesome-site
~ $ cd my-awesome-site
~/my-awesome-site $ jekyll serve
# => Now browse to http://localhost:4000

You can also use: jekyll build

And, working with drafts: jekyll serve —drafts

Jekyll documentation

Jekyll repository on GitHub

✑ Set up Git:

Jekyll’ structure


Ruby Gems


Using Jekyll with GitHub Pages:

Jekyll Pages

GitHub Pages are powered by Jekyll so you can deploy a site from a GitHub directory and host it for free.

GitHub: Using Jekyll with pages — Pages help & how-to.

Setting up your GitHub Pages site locally with Jekyll

Editing remotely

Prose — Prose is a simple content editor for GitHub designed for managing websites. Useful to edit your Jekyll site from any computer, work in team etc.

There are other services like Netlify and cloudcannon that integrates Jekyll and extend its power.

Jekyll themes:

Minima is the current default Jekyll theme A collection of free Jekyll themes

→ A handful of Jekyll Themes compiled by By Shu Uesugi

→ Dr Jekyll’s themes — is a free static website theme directory

Alembic, is a Jekyll boilerplate theme designed to be a starting point for any Jekyll website

Learning Jekyll

Getting Started with Jekyll by Nicholas Cerminara (@nickforthought). This is one of the most thorough article on how to set up a Jekyll site in a few comprehensive steps. — Step by step tutorials and screencasts covering everything you need to know about Jekyll.

✑ Jekyll Talk — A place for the Jekyll community to ask questions, get help, and share their wonderful creations!

An Introduction to jekyll by Jérôme Coupé

✑ Add a portfolio to your jekyll site:

✑ Jekyll SEO: Brett Hardin’s Jekyll and seo optimization

Jekyll or WordPress?

Jekyll is gaining more and more attention. Once set up, maintaining a Jekyll blog is convenient and hassle-free. Simplicity, focus on writing and the speed advantage Jekyll provides make it an ideal tool for blogs. There are a lot of articles around about people converting their WordPress blogs to Jekyll. Or glossing about going back to WordPress and why. In the end what you use doesn’t matter. These are both fantastic tools. Their beauty is that once you adapt them to your needs, they will remain behind the scene. The important thing is what you make out of them.

Other static site generators

Here is a list of more Open-Source Static Site Generators, complete with stat usage and info.

Credits for this site runs on Jekyll. The theme for this site is based on minimal mistakes by Michael Rose. Read the Minimal Mistakes theme setup for thorough documentation and comprehensive install how-to. Thanks to @mmistakes for sharing his excellent work — you can find more open source themes by Michael Rose here and on GitHub.

Further reads

Tom Preston-Werner(@mojombo). “Blogging Like a Hacker.”
Young Hahn, Development Seed. “Using Jekyll and GitHub Pages For Our Site.” — a thorough article about how Jekyll works.
Mathias Biilmann Christensen, Smashing Magazine “Why Static Website Generators Are The Next Big Thing.” (November 2015) same article, discussed on HN
  1. It works on Windows too. 

Categories: Jekyll



Leave a comment