Jekyll - Step by Step

This article is intended for beginner.

Goal: Explain Jekyll Directory Step by Step

Table of Content

Here, I present a Jekyll Tutorial, step by step, for beginners.

Table of Content
Preface
1: Jekyll Build/ Serve
2: Config: _config.yml
3: Layout: index.html dan _layouts/default.html
4: Example Page: salam.html
5: Includes: _includes/head.html
6: Custom directories: for pages dan assets
7: Post: _posts, _layouts/post.html
8: Directory Structure: Real Life Site
Conclusion

Salam mean greet, in Indonesia Language

Preface

Jekyll is an SSG (Static Site Generator) that is supported by github. Jekyll is not the only SSG (Static Site Generator).

Static Site Generator

SSG is a tool to make a site that contain static HTML.

Input: Code in files.
Output: Corresponding HTML files.

So basically, we cannot use any dynamic site feature, such as form, or database input-output, and so on.

Because this site is static, it is lighter for server to handle, no overhead to process PHP or RoR or stuff. No need for database processing either.

Static side is also considered safer in security context. No input -output means, minimize server security hole.

List of Static Site Generator

In case, that you need a broader view about SSG. Here is a list:

Hugo (go)
Hexo (nodejs/npm)
Cobalt (rust)
Pelican (python)
Jekyll (ruby)
Sculpin (php)
Gatsby (nodejs/npm)

If this list above is not enough, you might consider to have a look at staticgen.com

How Does It Works

Static Site: Server only transfer files in directory

either HTML, CSS, Javascript or CSS.
Dynamic Site: Server, process script for each request. For example: PHP script has html output, even in the client it is still has .php extensions. The rest is usually static: HTML, CSS, Javascript or CSS.
SSG: Server make a static site, everytime there is a change in code. In local PC: Everytime we save from text editor in SSG working directory. In github: Every commit to Jekyll Site repository.

In short: server load only happened after commit. The rest, server only transfer static data to client (browser). That is why the server is lightweight.

Why Jeykll ?

Jekyll in context of its relation to github, is easy for beginner, You can just uploaded it to github, and you can view your github.io site, right away, just like that.

Honestly, this is the only SSG that I ever use in my real life site. So my opinion could be changed over time.

Why Not Jeykll ?

In fact I have migration plan to Hugo.

After blogging time to time, after 194 article, Jekyll become so slugish. It is because Jekyll is based on Scripting Language (Ruby) that should be interpreted from to to time. Meanwhile Hugo is binary based. That is why Hugo is faster.

If you only have a few article below a hundred, Jekyll is perfectly fine.

Begin The Guidance

Let’s get the tutorial started.

1: Jekyll Build/ Serve

It only takes a few steps.

1. First

% jekyll -v
jekyll 3.7.0

2. Second

% mkdir ~/githublab/jekyll

3. Other Step

% cd ~/githublab/jekyll

4. An Another

% jekyll build
Configuration file: none
            Source: /home/epsi/githublab/jekyll
       Destination: /home/epsi/githublab/jekyll/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.046 seconds.
 Auto-regeneration: disabled. Use --watch to enable.

Or you can right away use this command below.

5. And The Last One

% jekyll serve          
Configuration file: none
            Source: /home/epsi/githublab/jekyll
       Destination: /home/epsi/githublab/jekyll/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.017 seconds.
 Auto-regeneration: enabled for '/home/epsi/githublab/jekyll'
    Server address: http://127.0.0.1:4000

Jekyll: Start

Notes

The directory _site has been made automatically.

Project Tree

% tree
.
└── _site

1 directory, 0 files

Jekyll: Tree

Preview

It is time to refresh your browser to http://localhost:4000/

Jekyll: Browser

Jekyll New

Some tutorial use an easier way to create a Jekyll Skeleton, but I do not use it in this tutorial, because I need to explain, step by step.

$ jekyll new .

I simply ignore this command.

2: Configuration

Consider make our configuration: _config.yml

Don’t let the config intimidate you. This is mostly just a description YAML format.

_config.yml

# Welcome to Jekyll!

# Site settings
title: Yet Another Open Source Blog
email: epsi.nurwijayadi@gmail.com

description: > # description below
  Learn and Discover Open Source with Daily Genuine Experience.
  From Coding, Design, Package Management Tweak to Desktop Customization.

baseurl: "" # the subpath of your site, e.g. /blog

# the base hostname & protocol for your site
# url: "http://epsi-rns.github.io" 
url: "http://localhost:4000" 

# Missing timezone in metadata date can lead to wrong date in url
timezone: Asia/Jakarta

Notes

No _site\index.html has been made. This will be automatically made later.

Project Tree

$ tree
.
├── _config.yml
└── _site

1 directory, 1 file

Jekyll: YAML Configuration

3: Layouts

Consider make these three artefacts.

Directory: _layouts
File: index.html
File: _layouts/default.html

Project Tree

$ tree
.
├── _config.yml
├── _layouts
│   └── default.html
├── _site
│   └── index.html
└── index.html

2 directories, 4 files

Content

With content as below:

index.html

---
layout: default
---
    <p>Hola Amigos, Saludos a todos.<br/>
    Buenos Dias/Tardes/Noches.</p>

    <p>Quiero aprender Jekyll.<br/>
    Larga Vida Jekyll!<br/>
    </p>

    <h4>Felicitaciones.</h4>
    <p>Y Perdon por mi espanol.<br/>
    Soy de Indonesia.<br/>
    Estoy usando Jekyll.</p>

_layouts/default.html

<!DOCTYPE html>
<html lang="en">

<head>
    <title>{{ site.title | escape }}</title>
</head>

<body>

    <div class="page-content">
      <div class="wrapper">
        {{ content }}
      </div>
    </div>

</body>
</html>

Notes

We need to pay attention to these artefacts:

Frontmatter in: index.html

---
layout: default
---

Liquid snippet in: _layouts/default.html

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

Preview

It is time to refresh your browser to http://localhost:4000/

Jekyll: Plain

4: Example Page

Instead of using index.html, we need another example. Consider make salam.html. It means greet in Indonesia. This file will be using default layout.

salam.html

---
layout: default
---
    <p>Apa kabar kawan-kawan, Salam semuanya.<br/>
    Selamat Pagi/Siang/Sore.</p>

    <p>Saya sedang belajar Jekyll.<br/>
    Hidup Jekyll!<br/>
    </p>

    <h4>Selamat.</h4>
    <p>Maafkan bahasa Indonesia saya.<br/>
    Saya berasal dari Indonesia.<br/>
    Saya menggunakan Jekyll.</p>

Preview

Now we can happily see the result in http://localhost:4000/salam. The browser title set in _layouts/default.html. We can set it per pages later, using frontmatter.

Notes

If you want, you can use other format, instead of HTML, such as markdown.

Jekyll: Example Page

5: Includes

Now consider preparing these artefacts:

Directory: _includes
File: _includes/head.html
Icon: favicon.ico

And change these artefacts

Liquid File: _layouts/default.html
Frontmatter in File: salam.html

Project Tree

$ tree
.
├── _config.yml
├── _includes
│   └── head.html
├── _layouts
│   └── default.html
├── _site
│   ├── favicon.ico
│   ├── index.html
│   └── salam.html
├── favicon.ico
├── index.html
└── salam.html

3 directories, 9 files

_includes/head.html

Again, do not let these code below intimidate you. This is just an example of liquid template.

<head>
  <title>{% if page.title %}{{ page.title | escape }}{% else %}{{ site.title | escape }}{% endif %}</title>
  <link href="{{ site.url }}/favicon.ico" rel="shortcut icon" type="image/vnd.microsoft.icon" />
</head>

You should see that any directory or any file, except with prefix _ is rendered in _site directory.

Liquid: _layouts/default.html

<!DOCTYPE html>
<html lang="en">

  {% include head.html %}

<body>

    <div class="page-content">
      <div class="wrapper">
        {{ content }}
      </div>
    </div>

</body>
</html>

Frontmatter: salam.html

---
layout: default
title:  Salam Pramuka
---

Preview

Check your browser for these two

http://localhost:4000/
http://localhost:4000/salam

Pay attention that both have different title :

salam.html as set locally in frontmatter
index.html as set globally in _config.yml

You should also see the favicon.ico.

6: Custom Directories

This part is where we put html pages dan images. Like said before, any directory or any file, is rendered in site directory, except with prefix .

Consider make these two directories.

pages (for any html pages other than _post)
assets (for anything else: images, css, javascript)

Project Tree

$ tree -I _site
.
├── _config.yml
├── _includes
│   └── head.html
├── _layouts
│   └── default.html
├── assets
│   └── logo-orb-spiral.png
├── favicon.ico
├── index.html
└── pages
    └── salam.html

4 directories, 7 files

Assets

Put any picture into assets directory For example: assets/logo-orb-spiral.png

Pages

Move salam.html into pages/salam.html

Dan change a little bit, add picture image in this document.

---
layout: default
title:  Salam Pramuka
---
    <p>Apa kabar kawan-kawan, Salam semuanya.<br/>
    Selamat Pagi/Siang/Sore.</p>
    
    <a href="{{ site.url }}">
        <img src="/assets/logo-orb-spiral.png" 
             alt="{{ site.title }}" />
    </a>

    <p>Saya sedang belajar Jekyll.<br/>
    Hidup Jekyll!<br/>
    </p>

    <h4>Selamat.</h4>
    <p>Maafkan bahasa Indonesia saya.<br/>
    Saya berasal dari Indonesia.<br/>
    Saya menggunakan Jekyll.</p>

Jekyll: Custom Directory

7: Posts

We are almost finished. Now it is time to make a post. Consider preparing these artefacts:

Directory: _posts
Example Post: _posts/2018-02-20-using-jekyll.markdown
Layout Post: _layouts/post.html
Add Post List Code in: index.html

Project Tree

$ tree -I _site
.
├── _config.yml
├── _includes
│   └── head.html
├── _layouts
│   ├── default.html
│   └── post.html
├── _posts
│   └── 2018-02-20-using-jekyll.markdown
├── assets
│   └── logo-orb-spiral.png
├── favicon.ico
├── index.html
└── pages
    └── salam.html

5 directories, 9 files

Frontmatter: _posts/2018-02-20-using-jekyll.markdown

---
layout: post
title:  "Using Jekyll"
date:   2018-02-20 09:17:35 +0700
author: epsi
---

### Preface

My first article.

_layouts/post.html

As a content of default layout.

---
layout: default
---
  <div class="post-content">
    {{ content }}
  </div>

index.html

---
layout: default
---
  ...

  {%for post in site.posts %}
    <ul>
      <li>
        <a href="{{ post.url }}">
          {{ post.title }}
        </a>        
      </li>      
    </ul>
  {% endfor %}
{% endraw %}

Note

Post can be either HTML format or markdown format.

Preview

Again, check browser for both URL:

http://localhost:4000/ And clik link to open below URL:
http://localhost:4000/2018/02/20/using-jekyll.html as set in date in frontmatter.

Jekyll: _post

8: Directory Structure: Real Life Site

In real life site, we can expand directory structure. This is an eaxample from my current blog:

1: pages

$ tree -d pages
pages
├── _layout_test
├── desktop
└── webdev

2: assets

$ tree -d assets -L 2
assets
├── posts
│   ├── code
│   ├── design
│   ├── desktop
│   ├── opensource
│   ├── system
│   └── webdev
├── site
│   ├── images
│   └── js
├── themes
│   ├── default
│   └── oriclone
└── vendors
    ├── bootstrap
    ├── font-awesome
    ├── jquery
    └── lunr

Details

$ tree -d assets/posts/code 
assets/posts/code
├── 2016
│   └── 05
├── 2017
│   ├── 04
│   └── 12
└── 2018
    └── 01

3: _includes

$ tree -d _includes
_includes
├── layout
├── page
├── panel
├── part
├── post
│   ├── 2017
│   │   ├── 04
│   │   ├── 05
│   │   ├── 06
│   │   └── 08
│   └── 2018
│       └── 01
└── service

13 directories

Jekyll: Tree _includes

4: _posts

$ tree -d _posts   
_posts
├── code
│   ├── 2016
│   ├── 2017
│   └── 2018
├── design
│   ├── 2015
│   └── 2016
├── desktop
│   ├── 2014
│   ├── 2015
│   ├── 2016
│   ├── 2017
│   └── 2018
├── opensource
│   ├── 2014
│   ├── 2016
│   └── 2018
├── system
│   ├── 2014
│   ├── 2015
│   ├── 2016
│   ├── 2017
│   └── 2018
└── webdev

24 directories

Jekyll: Tree _post

Jekyll is very flexible in context of directory management.

Conclusion

I think this is all for now.

There are other topic though, such as bootstrap (with SaSS) in Jekyll in other article. And a bunch of enhancement. This is already a very long article, so I have to close the guidance. See you with the next tutorial.

Thank you for reading.