Jekyll is really simple once you know how it works. You can make your blog do wonders if you know how to play with templates, layouts, curly braces et al. Create yourself a clean, minimal and beautiful Jekyll blog.
Why learn Jekyll the right way?
When I had to make some changes in my Jekyll blog, I used to write dirty code in respective templates and somehow made it work for a while.
But if I wanted to make any further changes to it then I have to search for the code, see how it used to work, edit or add some more dirty code and make it work again!
- Why learn Jekyll the right way?
- How to use Jekyll?
- What Jekyll does better?
- Understand the structure of Jekyll
- Files inside a Jekyll site
- Folders inside a Jekyll site
These dirty code blocks would break my site, leading to undesirable results. Sometimes I wouldn’t know what exactly went wrong.
I never used to add comments while committing the changes (big mistake). I can always revert back, but I would lose all the changes and posts :(
This is what I used to do years ago. Half knowledge is worse than no knowledge was completely true in my case.
My point is, don’t do it like me. Do it the right way. You don’t have to master this overnight. Take time. Read more about Jekyll. Not just my articles, any good piece you can get online. Practice with a simple website or blog.
How to use Jekyll?
When I started using Jekyll, I used to get a lot of 404 errors, page build errors, liquid tag errors, page rendering errors and what not. The horrible mistake I did was not spending a little time to know how Jekyll works. I was over enthusiastic may be. But it did hurt me in the long run.
If you are just starting off with Jekyll or you do not know how to use Jekyll then please start with the official documentation provided by Jekyll. This will set you on the right track. It has a lot of information (and a lot of pages as well).
So I thought I would summarize it in this post so that anyone can make use of it for a basic Jekyll blog designing.
But once you finish reading this post, I suggest you to check the documentation. It will give you a rather deep insight than just a brief introduction like this one.
What Jekyll does better?
As depicted in the image(pardon my photoshop skills), Jekyll does magic on text files converting them into html files - which is technically called as “text transformation“. This is not the only thing Jekyll does. Jekyll actually does some more magic like templating, pagination, syntax highlighting, etc.,
And also, Jekyll posts and pages can be written in easily readable markups like markdown, text, textile (not supported anymore after Jekyll 3.0 update) etc.,
Understand the structure of Jekyll
Jekyll is simple if you understand what feature is for what purpose. Let us look at the folder structure of Jekyll. The below tree is taken directly from Jekyll documentation.
.
.
├── _config.yml
├── _drafts
| ├── begin-with-the-crazy-ideas.textile
| └── on-simplicity-in-technology.markdown
├── _includes
| ├── footer.html
| └── header.html
├── _layouts
| ├── default.html
| └── post.html
├── _posts
| ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
| └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _data
| └── members.yml
├── _site
├── .jekyll-metadata
└── index.html
Keep this sample Jekyll repository tab open while reading the below points. You should be able to see the following files and folders.
Files inside a Jekyll site
1. _config.yml:
Master configuration file _config.yml is the DNA of a Jekyll project. You can define your site configurations inside this file. From simple things such as title, URL, author, pagination etc., to complex things such as SSL certificates, increments etc., can be defined inside this file.
Here is a sample _config.yml file for Emerald Jekyll theme. You can use all the parameters in this file using site variable.
For instance, using {{ site.url }} anywhere on the page, post, template will fetch the url variable defined in _config.yml. Read More.
This is also the first file you should edit when you fork(copy) a new theme. In order to make your blog work, you should mention the baseurl. Read: How to create a Jekyll blog for more.
2. index.html:
This is your homepage in most cases. It can also be in the format index.md. It usually has a for loop to load all the posts. You can make changes to this file and design your index of posts like how I have done the card layout for my blog.
Index file may also call default layout which will be inside _layout folder. You can also remove the whole loop thing and have a simple introduction page like the Jekyll official site.
3. atom.xml/sitemap.xml:
This can be your feeds file or a sitemap. If you do not have one, you can always create a sitemap or a feeds file.
4. readme.md:
This is a file where you can describe your project. This will be rendered as a html file and displayed by default when someone visits your repository on Github. In this link, observe the page displayed.
At the bottom of the repository, you will see a description of the theme with a screenshot. This file is not mandatory.
Folders inside a Jekyll site
1. _includes:
This folder is kind of like libraries that are called using #include in C-programming. You can include files which are inside this folder into any post or page just by adding this line of code - {% include filename.html %} replace the filename to a file inside your _includes folder.
Usually, header and footer files are put inside this folder and called inside default layout (or any page or post).
2. _layouts:
As the name says this folder contains your website layouts. It will have default, page and post layouts by default. You can also create other layouts such as two column, single column etc.,
This is where you can change the looks of your post and pages. If you look at this website for example, posts look different from pages. The reason is that they use different layouts.
There can also be a layouts for redirecting, compressing etc.,. I will talk about these in a different post.
3. _posts:
All your blog posts reside here. The naming should be in the format YYYY-MM-DD-title.md.
4. _sass:
Jekyll supports Sass preprocessor. Sass files are included in this folder can be imported to main stylesheet. Read for a brief section on sass.
5. _site:
This is a folder created by Jekyll to host your website. It will have files only compatible for a browser - HTML, CSS, JS, XML etc., This conversion happens by default. You don’t have to create this or edit anything inside this folder.
This folder gets generated only when you are using Jekyll locally. If you are hosting your website using Github Pages then you don’t see this folder in your repository because Github Pages does it for you in the background.
6. css, images, js:
You can create folders and name them as per your needs. These are some of the common folders that we use to keep stylesheets, images, and JavaScript files.
7. Other folders:
There can be other folders as well. The one used for plugins is _plugins. You can add any arbitrary folder. You can name it anything, say project and keep a html or a markdown file inside it. These files will get a URL http://yourdomain/project/filename.html. You can change that to http://yourdomain/project/filename/ by using permalinks.
Here is a video on how Jekyll works
I hope that gives you an insight into the structure of Jekyll files and folders. It looked strange for me in the beginning but once I understood the logic used behind, it all made sense. And since a Jekyll site is made up of a lot of different parts, debugging is very easy.
When something starts acting up, you’ll know exactly where to look for. In this blog, I have written a lot of things I did using Jekyll. Make use of it.
If you get frustrated about something that is not working then just ask the community. Google things with the suffix jekyll. You will find an answer. You can always ask me here, in the comment section. I will try my best to help you out.
Read: Common Jekyll Issues
Fixing Page Build Errors
Thanks for reading!
