This post introduces the directory structure of Jekyll to help people understand the Jekyll project environments. We also discuss some basic concepts such as templates and includes.

Jekyll

Jekyll is one of the most popular static site generators (SSGs). It is written in Ruby and is supported by GitHub Pages.

The Jekyll document is comprehensive and instructive. So, I encourage people to read the documentation if they decide to use it. Here, I will introduce Jekyll from my perspective and provide a general idea of how Jekyll works.

Prerequisites and Installation

Since jekyll is software written in Ruby, we first need to ensure the programming language is installed on our computer. It comes with Linux distributions. We can check it using the command.

$ ruby -v	# display ruby version info

We can also follow the Quickstart in Jekyll documentation to create a quick jekyll project and view it in the browser.

Directory Structure

Jekyll creates a series of directories. It is essential to understand their functions to create the pages we want. A typical jekyll directory is like the following (from Jekyll documentation):

.
├── _config.yml
├── _data
│   └── members.yml
├── _drafts
│   └── on-simplicity-in-technology.md
├── _includes
│   ├── footer.html
│   └── header.html
├── _layouts
│   ├── default.html
│   └── post.html
├── _posts
│   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
│   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
│   ├── _base.scss
│   └── _layout.scss
├── _site
└── index.html    # can also be an 'index.md' with valid front matter

_posts directory contains all blog content. The content is usually written by Markdown. Each file corresponds to an individual post page and the filename should follow the convention YEAR-MONTH-DAY-title.md.
_draft directory stores the drafts, and the files in it are not generated into pages, acting like the unpublished _post directory.
_layout directory contains the templates written in HTML, which describes the skeleton for web pages.
_include directory stores the frequently used HTML snippets which are used by include command.
_sass directory stores the cascade style sheets (CSS), which specify the display format of HTML file.
_data (or assets) directory stores resources to build the website, such as images, pdf, and js codes.
_config.yml is the configuration file for Jekyll. We can specify build configurations and define global variables in this file.
index.html (or index.md) is the index page, which is the default page to show when accessing the blog.
_site directory stores the generated static web pages.

To summarize, the following three directories relate to web page design and display:

_layout
_include
_sass

The following three are the most edited ones after we set the page style:

_posts
_draft
_data (or asset)

For any build or global configuration, we check

_config.yml

Some comments for index.html and _sites.

When we access a web server, each directory has an index page. By default, the web server will send the index page back to the user if the user does not specify in detail which HTML file to look for. Therefore, index.html serves as the blog’s homepage.

Jekyll is an SSG that does not render the page dynamically. It generates everything in competing HTML pages in advance and outputs them to _site. We can upload the _site directory to the web server (e.g., Github Page) for online views.

Layouts

A layout file is an HTML file that specifies the structure of a web page. It defines the template that all pages will follow. We can define different layout files for various styles.

We generally have a base layout named default.html, which defines the skeleton of all web pages. It needs to contain the <html> element (a complete HTML file). A typical default.html looks like the following.

<!DOCTYPE html>
<html>
{% include head.html %}
    <body>
      
      	<div class="container">
      	{% include header.html %}
      	<div class="page-content wrapper">
        	{{ content }}
      	</div>
      	{% include footer.html %}
    	</div>
      
  	</body>
</html>

The base layout does not need to include detailed structures. We can use other templates and HTML snippets for finner decorations.

For convenience, other layouts (e.g., post.html) can inherit the structure in default.html and do finner templating. For example, a typical post.html looks like the following.

---
layout: default
---
<div class="post">
	<header class="post-header">
      	<h1 class="post-title">{{ page.title }}</h1>
    </header>
  
    <article class="post-content"> 
      	{{ content }}
    </article>
  </div> 

Three things for notice:

We add the variable layout: default in the front matter to make the post.html inherit from default.html.
The inheritance means that all contents of post.html will replace {{ content }} in the default.html.
The inherited layouts do not need to be complete HTML files. i.e., does not need to contain <html> elements.

Includes

Includes are the frequently used HTML snippets by the include command. For example, a typical footer.html snippet looks like the following.

<footer class="site-footer">
    <p>Copyright &copy; <a href="/">HuskyDev</a></p>
    <p>Powered by <a href="https://github.com/jekyll/jekyll">Jekyll</a> 
</footer>

Includes are not layouts. They are independent HTML snippets and do not need a template. We can include them anytime we want.

How to Get Started

My suggestion is to start by understanding the basics of HTML and CSS, such as grammar and formats. Many nice tutorial websites already exist, for example, W3Schools HTML Tutorial and W3Schools CSS Tutorial.

Then, navigate the _layout directory to understand the structure of templates that are used in the website. Start from default.html (or default layout with other names). Try to ignore the templating variables and statements in the layouts. Take a look into the _include directory if any template uses include.

After that, we will have a basic knowledge of how a web page is designed and which part of the template controls it. Now, it is time to start learning the templating language and Jekyll.

Always remember that Jekyll is an automation tool that helps us to fill the designed template with the written posts. The posts written by Markdown are easy to read and understand. However, they are not well formatted and not in the HTML format used on the web. Jekyll converts everything into HTML files. This perspective helps us to grasp the big picture of Jelyll and SSGs.