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
Notes
The directory _site has been made automatically.
Project Tree
% tree
.
└── _site
1 directory, 0 files
Preview
It is time to refresh your browser to http://localhost:4000/
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
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/
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.
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>
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.
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
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 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.