Webmasters Gallery

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.

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.

Installing Jekyll

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

OS X

$ gem install jekyll -v 2.4.0

Ubuntu

$ apt-get install ruby ruby-dev make gcc nodejs
$ gem install jekyll -v 2.4.0

Windows

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:

$ 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 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, 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 }}.

</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

---
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`:

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

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

...
<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.

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: post
title: What is Coffee?
category: Information
---
Coffee is a brewed drink prepared from roasted coffee beans, which are the seeds of berries from the Coffea plant. The Coffea plant is native to subtropical Africa and some islands in southern Asia. The plant was exported from Africa to countries around the world and coffee plants are now cultivated in over 70 countries, primarily in the equatorial regions of the Americas, Southeast Asia, India, and Africa. The two most commonly grown are the highly regarded arabica, and the less sophisticated but stronger and more hardy robusta. Once ripe, coffee beans are picked, processed, and dried. Green (unroasted) coffee beans are one of the most traded agricultural commodities in the world. Once traded, the coffee beans are roasted to varying degrees, depending on the desired flavor. Roasted beans are ground and brewed to produce coffee as a beverage.

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`:

---
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 | date: '%B %d, %Y' }}</span></p>
    {{ 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:

---
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 Coffee Cafe site.

Stay tuned the next few days as we level up this site with some powerful editing abilities and features.

Building a Jekyll Site – Part 1 of 3: Converting a Static Website To Jekyll is a post from CSS-Tricks