Exploring Jekyll Directory Structure

7 minutes read

The second part of Jekyll tutorial, Beside of directory structure, you’re going to see how to create a blank project by yourself.

In the previous post, you’ve learned how to set up your environment. Now in this post, you’re going to know how Jekyll directory structure works and how you can create your first blank project.

Text Editor

Text editors are great tools that help us to edit any documents. Without them, edit these documents would be a “pain in the neck.” You can use your default text editor the come with your operational system or you can even use Microsoft Word, LibreOffice or the Google Docs “word-version.”

But I’ll recommend these “most powerful” text editors. They’re lightweight, and they have a bunch of plugins that turn our life easier.

Atom (All platforms).

Brackets (All platforms).

Sublime Text (All platforms).

Notepad++ (Windows only).

For this tutorial, I’m using Windows as my environment with Atom as my text editor, let’s get started!

Jekyll Directory Structure

Directory Structure

A basic Jekyll site usually looks something like that you see in the picture above.

We have a _config.yml files that contain the options used by the application to modify its behavior.

We have a _includes folder, where we can put the HTML files such as head.html, header.html, footer.html.

We have a _posts folder, and here you can create your posts files following the format: YEAR-MONTH-DAY-title-MARKUP.

To not waste this post writing all the files and the folders contented in the picture, you can read the complete definition here.

Minima Theme

Minima is a one-size-fits-all Jekyll theme for writers. It’s Jekyll’s default (and first) theme.

If you followed the instruction of the first part of this tutorial, we’ve created the myblog project, right!? If you opened the project folder, you must’ve seen the following files and folders.

Files and Folders

Now you’re asking yourself: - Where are the other files and folders?

They are in Ruby’s gem folder. To know where the gem folder is, open your command prompt or terminal (if you’re on Linux or Mac OS X), go to myblog folder and type:

bundle show minima

cmd

If you open your project in a text editor, it will seem like this.

Files and Folders2

Now you see the remaining files and folders. Now I’m going to teach you how to create an empty project.

Creating The Blank Project

The minima themes are pretty cool but if I want to create my project without the minima template by default?

It’s possible, and it’s simple. First, we need to choose a new local to create our new project. I’ll create my new project into my Documents folder, feel free to choose your personal folder place to create our new project. Into the folder you’ve selected, you’re going to type:

jekyll new awesome-blog --blank

cmd2

If you open your project in a text editor, it will seem like this.

j3

If you noticed, our project don’t have the _config.yml, _sites, _posts and the others files and folders. What will happen if we try to run our project for the first time?

cmd4

Installing Ruby Devkit (Windows only)

If you’re using Windows as your Ruby/Jekyll develop environment, we need to install the Devkit for some gems that need the build tools installed.

If we type jekyll serve in command prompt, we’ll see.

cmd3

It’s running but, it’s complaining that it’s missed the gem wdm on Gemfile, so let’s create it!

After we’ve created the Gemfile, we need to install wdm but before installing it, we need to install the Ruby Devkit first.

Go to Ruby Devkit and download the DevKit-mingw64.

After downloaded it, create a folder in any place and name it. I created my folder in C:/ with the Devkit name.

You can use chocolatey to install the Devkit too. Just type: choco install ruby2.devkit and follow the next step.

Using command prompt, go into the folder where you extracted the Devkit and type:

#Gemfile
ruby dk.rb init

Now we need to open the config.yml and set our ruby path. If you’re using chocolatey to install Ruby and Jekyll, the Ruby path is in X:/tools/ruby23, copy this path and paste on config.yml file.

# config.yml in Devkit folder
# Example:
# ---
# - C:/ruby19trunk
# - C:/ruby192dev
# ---

- C:/tools/ruby23

After that, save and close the config.yml file, get back to the command prompt and type:

#Gemfile
ruby dk.rb install
=>[INFO] Updating convenience notice gem override for 'C:/tools/ruby23'
=>[INFO] Installing 'C:/tools/ruby23/lib/ruby/site_ruby/devkit.rb'

If you don’t see any errors, we need to install wdm gem, type:

#Gemfile
gem install wdm

After installing it, copy and paste on your Gemfile the line gem ‘wdm’, ‘>= 0.1.0’.
Our Gemfile going to look like this.

#Gemfile
source "https://rubygems.org"

gem "jekyll", "3.4.3"
gem 'wdm', '>= 0.1.0'

If we type jekyll serve on the command prompt we won’t see the server complaining about any missed gem anymore.

Back To Our Project

If we put the http://127.0.0.1:4000/ in our browser, we’ll see a blank page

If we put a single h1 tag in our index.html file and then refreshing the browser, we’ll see something inside the tag.

#index.html
<h1>Hello</h1>

Now we need to create the _includes, _assets folders.

Inside of _assets folder, create the CSS folder and inside of CSS folder create the main.css file.

Index.html

Index.html is the homepage of your blog. If you noticed, there is a triple-dashed lines with some text inside it. It is called Front Matter.

Front Matter is where Jekyll starts to get really cool. Jekyll will process any file that contains a YAML front matter block as a special file.

The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines.

Inside of the Front Matter, we have some predefined global variables, in the index.html file, I used one predefined variable, it’s layout.

Text Editor 1

The layout is one of the three predefined variables (to see the other two).

If set, this specifies the layout file to use. Use the layout file name without the file extension. Layout files must be placed in the ‘layouts’ directory.

includes, layouts, posts and site folders

The _includes folder is where we set the layout of our blog. Here I created three HTML files, head, header and footer and in each one of them, I built the layout structure of our page.

head.html head.html

header.html header.html

footer.html footer.html

The _layouts folder is where we define the layout of our pages. Remember when I cited about Front Matter, triple-dashed lines and so on, got it!? Bear in mind that inside of these triple-dashed lines I’ve set the ‘layout: default’ variable? Here we can create our default, page and post page. In this example, I created the default.html and post.html only.

default.html default.html

post.html post.html

If you’ve noticed in the post.html file, there is a front matter with ‘layout: default’ inside it, it means that post.html is inheriting all the properties of the default.html file.

You’ve noticed some text inside of double braces too, didn’t you? These are global, site and page variables that Jekyll makes a variety of data available via the Liquid templating system.

The _post folder is where we create our posts. To create a post we need to follow the format YEAR-MONTH-DAY-title.MARKUP or YEAR-MONTH-DAY-title.MD, example: 2017-05-03-example.markup or 2017-05-03-example.md.

post file example

markup

The _site folder is where the generated site will be placed (by default) once Jekyll is done transforming it.

Running the project

Now it’s time to type jekyll serve to run and see our awesome-blog.

You can download the complete awesome-blog here.

Thank you guys for reading this article, I’ll hope you enjoy it, any question about it, leave a message below.