The following is a guest post by Mike Neumegen from CloudCannon.

Mike and I
talked about doing a little series on building Jekyll sites, which of course I was
into because Jekyll is great and more education around static site generators is
a good thing. Full disclosure, Mike's company CloudCannon is a CMS on top of
Jekyll. As part of this series he's going to show you how to use that, so I
requested it be a sponsored post.
This is a three-part series:
Part 1: (This post) Converting a Static Website To Jekyll
Part 2: Adding a Jekyll CMS with CloudCannon
Part 3: Creating a Firebase-Backed Commenting System

Static site generators are no longer just a tool for developers' personal blogs. Many companies
are turning to static technology for public facing websites, including Netflix, GitHub and
Atlassian.
Jekyll is the most popular static site generator. It takes source files and generates a website of
static pages upfront, ready to serve to users directly. This is dierent from how a traditional
CMS works, such as WordPress. WordPress uses a server side language and database to
generate a page when requested by a user.
In this series, we'll cover the basics of developing sites with Jekyll. Starting by converting a
static site to Jekyll, adding a CMS for non-developers using CloudCannon, then building a
commenting system using Firebase.
This tutorial creates a site for a fictional Cafe called Coee Cafe. Here's a demo.

The site we're about to Jekylize.

# Installing Jekyll
Jekyll is a command line tool which needs to be installed before use.

# OS X
Command Line

$ gem install jekyll -v 2.4.0

# Ubuntu
Command Line

$ apt-get install ruby ruby-dev make gcc nodejs

$ gem install jekyll -v 2.4.0

# Windows

Windows is not oicially supported but there is a workaround.

# Setup
Download the source files for Coee Cafe if you want to follow along.
Run Jekyll to build and serve the site. Navigate to the directory in your terminal and run:
Command Line

$ cd path/to/site/files
$ jekyll serve

jekyll serve builds the static site to the _site directory within the same folder and

starts a web server locally. Navigate to http://localhost:4000 in your browser to view Coee
Cafe.

# Jekyll layouts
Repeating content is the biggest hassle of a purely static site. Jekyll layouts solve this issue. A
layout is an HTML file in the `_layouts` folder with placeholders for content.

# Creating a layout
In Coee Cafe, div.content and title are the only elements that change per page. The
easiest way to create a layout is by copying an existing HTML file. Copy `index.html` to
`_layouts/default.html` and replace the contents of div.content with {{ content }} .
HTML

</header>

<div class="content">
{{ content }}
</div>

<footer>

{{ content }} is a Liquid tag which is part of Jekyll's templating language.

# Setting a layout
To set `index.html` to use the default layout, we use front matter, a snippet of YAML at the top
of the file between lines of three dashes.
To set the layout of `index.html`:
1. Update the contents of the file to contain only the contents of div.content
2. Add layout: default to the front matter
index.html (with YAML)

--layout: default
--<section class="hero">...</section>
<div class="container">...</div>
<section class="cta">...</section>

The index page is generated with the default layout and has the file contents in place of {{
content }} . The website should look the same as before. Repeat the same process for all
other HTML files.

# Using page variables

To customize the title of each page, we set a front matter variable on each page and use it
in the layout. Add the title variable to `index.html`:
index.html (with YAML)

--layout: default
title: Home
--...

Output the variable in _layout/default.html with Liquid:

HTML

...
<title>{{ page.title }}</title>
...

The title tag now changes between pages. This reduces the unnecessary duplication in the
site, so you make future changes in one place.

# Blogging
Adding posts is almost the same process as adding a page. Posts are Markdown or HTML files
within the `_posts` folder with a filename formatted with
:year-:month-:day-:title.:extension .

Blog post file format

# Writing posts
The contents of a post is the same as a page, a front matter header and the contents of the file.
Create a file called `_posts/2016-01-01-what-is-coee.md`, then add the front matter
followed by the content of the post.

post.md

---

layout: post
title: What is Coffee?
category: Information
---

Coffee is a brewed drink prepared from roasted coffee beans, which are the seed

Source / Read more [Wikipedia](https://en.wikipedia.org/wiki/Coffee).

This separation of markup and data is core to the Jekyll philosophy. This allows for reuse of
the content anywhere in the site.

# Creating the post layout

The example above used a new layout called post . This layout will extend the default layout
and add post specific elements, such as the publish date and category. To achieve this in
Jekyll, we specify a layout inside a layout. Copy the following into `_layouts/post.html`:
post.html

--layout: default
--<div class="container">
<h2 class="spacing">{{ page.title }}</h2>

<div class="blog-post spacing">

<p class="summary">{{ page.category }}<span class="date">{{ page.date | dat

{{ content }}
</div>
</div>

Using Liquid, we output each variable from the front matter, just as we output title above.
The date variable is formatted with a Liquid filter.

# Listing posts

The final step is listing the blog posts in blog.html . Using a Liquid for loop, create an
element for each post in site.posts :
blog.html

--layout: default
title: Blog
--<div class="container">
<h2 class="spacing">Blog</h2>

<div class="blog-posts">
{% for post in site.posts %}
<div class="blog-post spacing">
<h3><a href="{{ post.url }}">{{ post.title }}</a></h3>
<p class="summary">
{{ post.category }}
<span class="date">
{{ post.date | date: '%B %d, %Y' }}
</span>
</p>
{{ post.excerpt }}
</div>
{% endfor %}
</div>
</div>

Jekyll provides built in variables used here which are not defined in the front matter:
url is the generated URL for the post which is usually
/:categories/:year/:month/:day/:title.html but there are many

configuration options
excerpt is a snippet taken from the start of post content
content is unused here but it displays the entire content of the post, exactly like {{

content }} in the layouts

# All done
In minutes we've gone from a static site to a Jekyll site with a blog. Here's a download link for
the final Jekyll Coee Cafe site.
Stay tuned the next few days as we level up this site with some powerful editing abilities and
features.

This is a three-part series:

Part 1: (This post) Converting a Static Website To Jekyll
Part 2: Adding a Jekyll CMS with CloudCannon
Part 3: Creating a Firebase-Backed Commenting System

Comments
Valerio
# FEBRUARY 9, 2016
if theres any italian reading, i wrote a very similar post at this website with a windows
installation of jekyll: http://www.webhouseit.com/creare-siti-e-blog-statici-con-jekyll/
this might be useful to the ones not speaking english :)

Kirk Boone
# FEBRUARY 9, 2016
Your timing could not have been better as Im currently looking at this option for small
clients. Thanks!

Jodie
# FEBRUARY 9, 2016
Excellent tutorial, cant wait for the next parts!

Pawe Grzybek
# FEBRUARY 9, 2016
Superb tutorial! Is there any reason why you use version 2.4 in this tutorial? Jekyll is now in
version 3.0.3 that comes with tons of nice new features. Githb Pages (really o en Jekyll
website owners use it as a hosting, including myself) in on Jekyll 3 as well.

Mike Neumegen
# FEBRUARY 9, 2016
Hi Pawel,

Well spotted, in the next step the tutorial goes through using CloudCannon which
currently only supports Jekyll 2.4 (Were working on supporting all versions of Jekyll
in the near future).
Mike

Andy
# FEBRUARY 10, 2016
Great post thanks. I have been casting around for a static website generator to run my
hobby-site that is just set up as a flat file system using Dreanweaver.
Is Jekyll ok for mid-sized (500 pages plus) static websites?
How does templating work, or is it really as simple ad using an existing htm page?
Thanks
Andy

Mike Neumegen
# FEBRUARY 10, 2016
Hi Andy,
Yes Jekyll will be fine to use for your site. Have a look at the Jekyll Layouts section in
the tutorial above to see how templating works. Its all HTML files with simple liquid.
Mike

Andy
# FEBRUARY 10, 2016
Just to note from previous post, Im not totally stoneage as I serve my htm pages as php to
enable me to import footers, headers, side panels etc etc.

Presumably Jekyll does the same sort of thing?

Apologies for the noob questions.
Thanks
Andy

Mike Neumegen
# FEBRUARY 10, 2016
Yes it does, the dierence comes when someone views the website. In the PHP
version it has to include the sections on-the-fly whereas in Jekyll the site is built
upfront so the sections have already been included.
Mike

John Nixon
# FEBRUARY 11, 2016
Ive tried using the tutorial files, and a default download from jekyll and both are showing
the page not found page when I click the URL

Mike Neumegen
# FEBRUARY 11, 2016
Hmm theyre working for me. Try downloading them from the GitHub interface. The
Jekyll site is on the Jekyll branch.
https://github.com/CloudCannon/coee-cafe

casual_reader
# FEBRUARY 11, 2016
The demo is very amateurish. On mobile the menu isnt responsible and it even contains a
horizontal scrollbar.

Mike Neumegen
# FEBRUARY 11, 2016
Thanks for the feedback. Ive fixed up the styles so the demo site is mobile friendly
now.

John Aspinall
# MARCH 2, 2016
I tried this on a static site I have, got everything generating OK but do not see a _layouts
folder anywhere? I have an _site folder but not _layouts. Do you have to manually create
this?

Mike Neumegen
# MARCH 2, 2016
Hi John,
Yes thats correct. You need to create the _layouts directory.

John Aspinall
# MARCH 3, 2016
OK cheers, whereabouts in the file structure does this folder go?

Mike Neumegn
# MARCH 3, 2016
Hi John,
_layouts live in the root of your site. You can see the source code for the completed
site here https://github.com/CloudCannon/bakery-store/tree/jekyll

This comment thread is closed. If you have important information to share, please contact us.

We have a pretty good* newsletter.

your@email.com

Subscribe