Building a Jekyll Site - Part 1 of 3_ Converting a Static Website to Jekyll

8/16/2019 Building a Jekyll Site - Part 1 of 3_ Converting a Static Website to Jekyll

1/13

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 different 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 Coffee Cafe. Here's a demo.

http://slate-oak.cloudvent.net/http://slate-oak.cloudvent.net/http://slate-oak.cloudvent.net/https://www.firebase.com/http://cloudcannon.com/http://blogs.atlassian.com/2013/03/making-atlassian-design-guidelines/https://css-tricks.com/building-a-jekyll-site-part-3-of-3/http://mikeneumegen.com/https://css-tricks.com/https://css-tricks.com/https://css-tricks.com/https://css-tricks.com/https://css-tricks.com/https://css-tricks.com/https://css-tricks.com/http://slate-oak.cloudvent.net/https://www.firebase.com/http://cloudcannon.com/http://jekyllrb.com/http://jekyllrb.com/http://blogs.atlassian.com/2013/03/making-atlassian-design-guidelines/https://github.com/blog/1939-how-github-uses-github-to-document-githubhttp://cloudcannon.com/customers/netflix/https://css-tricks.com/building-a-jekyll-site-part-3-of-3/https://css-tricks.com/building-a-jekyll-site-part-2-of-3/http://cloudcannon.com/http://mikeneumegen.com/


2/13

The site we're about to Jekylize.

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

OS X

Ubuntu

Windows

#

#

$ gem install jekyll -v 2.4.0

Command Line

#

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

$ gem install jekyll -v 2.4.0

Command Line

#


3/13

Windows is not officially supported but there is a workaround.

Setup

Download the source files for Coffee Cafe if you want to follow along.

Run Jekyll to build and serve the site. Navigate to the directory in your terminal and run:

builds the static site to the directory within the same folder and

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

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 Coffee Cafe, and 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 with .

#

$ cd path/to/site/files

$ jekyll serve

Command Line

jekyll serve _site

#

#

div.content title

div.content {{ content }}

{{ content }}

HTML

http://localhost:4000/https://github.com/CloudCannon/coffee-cafe/archive/master.ziphttp://jekyllrb.com/docs/windows/


4/13

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

2. Add to the front matter

The index page is generated with the default layout and has the file contents in place of

. The website should look the same as before. Repeat the same process for all

other HTML files.

Using page variables

To customize the of each page, we set a front matter variable on each page and use it

in the layout. Add the variable to `index.html`:

{{ content }}

#

div.content

layout: default

---

layout: default

---

...

...

...

index.html (with YAML)

{{

content }}

#

title

title

---

layout: default

title: Home

---

...

index.html (with YAML)

https://en.wikipedia.org/wiki/YAMLhttps://github.com/Shopify/liquid/wiki/Liquid-for-Designers


5/13

Output the variable in with Liquid:

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

.

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-coffee.md`, then add the front matter

followed by the content of the post.

_layout/default.html

...

{{ page.title }} ...

HTML

#

:year-:month-:day-:title.:extension

#


6/13

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 layoutThe example above used a new layout called . 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`:

Using Liquid, we output each variable from the front matter, just as we output above.

The date variable is formatted with a Liquid filter.

Listing posts

---

layout: post

title: What is Coffee?

category: Information

---

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

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

post.md

#post

---

layout: default

---

{{ page.title }}

{{ page.category }}{{ page.da

{{ content }}

post.html

title

#

https://docs.shopify.com/themes/liquid-documentation/filters


7/13

The final step is listing the blog posts in . Using a Liquid for loop, create an

element for each post in :

Jekyll provides built in variables used here which are not defined in the front matter:

is the generated URL for the post which is usually

but there are many

configuration options

is a snippet taken from the start of post content

is unused here but it displays the entire content of the post, exactly like

blog.html

site.posts

---

layout: default

title: Blog

---

Blog

{% for post in site.posts %}

{{ post.title }}

{{ post.category }}

{{ post.date | date: '%B %d, %Y' }}

{{ post.excerpt }}

{% endfor %}

blog.html

url

/:categories/:year/:month/:day/:title.html

excerpt

content {{

http://jekyllrb.com/docs/permalinks/https://docs.shopify.com/themes/liquid-documentation/objects/for-loops


8/13

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 forthe final Jekyll Coffee 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

content }}

#

https://css-tricks.com/building-a-jekyll-site-part-3-of-3/https://css-tricks.com/building-a-jekyll-site-part-2-of-3/https://github.com/CloudCannon/coffee-cafe/archive/jekyll.zip


9/13

Comments

Valerio# F E B R U A R Y 9 , 2 0 1 6

if there’s any italian reading, i wrote a very similar post at this website with a windowsinstallation 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

# F E B R U A R Y 9 , 2 0 1 6

Your timing could not have been better as I’m currently looking at this option for small

clients. Thanks!

Jodie# F E B R U A R Y 9 , 2 0 1 6

Excellent tutorial, can’t wait for the next parts!

Paweł Grzybek# F E B R U A R Y 9 , 2 0 1 6

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 oen Jekyllwebsite owners use it as a hosting, including myself) in on Jekyll 3 as well.

Mike Neumegen# F E B R U A R Y 9 , 2 0 1 6

Hi Pawel,

http://www.webhouseit.com/creare-siti-e-blog-statici-con-jekyll/


10/13

Well spotted, in the next step the tutorial goes through using CloudCannon which

currently only supports Jekyll 2.4 (We’re working on supporting all versions of Jekyll

in the near future).

Mike

Andy# F E B R U A R Y 1 0 , 2 0 1 6

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# F E B R U A R Y 1 0 , 2 0 1 6

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. It’s all HTML files with simple liquid.

Mike

Andy# F E B R U A R Y 1 0 , 2 0 1 6

Just to note from previous post, I’m not totally stoneage as I serve my htm pages as php to

enable me to import footers, headers, side panels etc etc.


11/13

Presumably Jekyll does the same sort of thing?

Apologies for the noob questions.

Thanks

Andy


Yes it does, the difference 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# F E B R U A R Y 1 1 , 2 0 1 6

I’ve 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


Hmm they’re working for me. Try downloading them from the GitHub interface. The

Jekyll site is on the Jekyll branch.

https://github.com/CloudCannon/coffee-cafe

https://github.com/CloudCannon/coffee-cafe


12/13

casual_reader# F E B R U A R Y 1 1 , 2 0 1 6

The demo is very amateurish. On mobile the menu isn’t responsible and it even contains a

horizontal scrollbar.


Thanks for the feedback. I’ve fixed up the styles so the demo site is mobile friendly

now.

John Aspinall# M A R C H 2 , 2 0 1 6

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# M A R C H 2 , 2 0 1 6

Hi John,

Yes that’s correct. You need to create the _layouts directory.

John Aspinall# M A R C H 3 , 2 0 1 6

OK cheers, whereabouts in the file structure does this folder go?


13/13

Date post:	05-Jul-2018
Category:	Documents
Upload:	om-shankar
View:	224 times
Download:	0 times

Building a Jekyll Site - Part 1 of 3_ Converting a Static Website to Jekyll

Documents