Jekyll Directory Structure

Preface

Let’s get organized, there’s a place for everything, and everything should be in their respectable place.

This article cover, folders and files management, inside Jekyll. I created this pattern based on my own experience. Different than basic example provide by Jekyll.

So you can have a tidy post archives, for your growing blog, without too much thinking. At least you won’t get lost with your own data, article, image and code.

Nomore Dead Links Sir !

Archiving posts could be boring because its nature of repetitive task. This long article is also boring. You have been warned.

But, it is important step that you should consider from very beginning of your Blog.

Mostly when you share your blog. Once it has been shared, you can’t just change your URL, or it would be a dead link.

Reference

Jekyll Directory is very flexible. If you came from framework, then you are going to love it. Before we dive into deeper directory, You might consider to read this official guidance.

• https://jekyllrb.com/docs/structure/

And see all real world example for this Blog.

• https://github.com/epsi-rns/epsi-rns.github.io/

Main Directory

Here we will see transformation from root directory to static page directory _site.

Jekyll Perspective

From the Jekyll perspective. It has these standard directories: _data, _includes, _layouts, _posts, _sass, _site.

├── index.html
│
├── _config.yml
├── _data
├── _includes
├── _layouts
├── _posts
├── _sass
│
└── _site

Every text files in main directory, except _site will be pre-processed into static site into _site directory.

For example a page index.html. Will be transformed into a static page _site/index.html. That can be called in web browser as http://localhost:4000/index.html without further overhead processing.

Anything started with _ are considered Jekyll’s internal. So it won’t be shown in _site.

For example a page _config.yml, or _config_dev.yml, won’t be in your live site.

Developer Perspective

From the Developer Perspective, I need to place my own stuff following my own flavour. Let’s get organized, there’s a place for everything, and everything should be in their respectable place.

• Be tidy. Minimize files in root directory. Don’t let your directory be bloated.

• Refactor. Keep your directory clean. No directory contain too many files.

├── index.html
│
├── assets
└── pages

The assets directory contains images, stylesheet, font and javascript, all at once. Meanwhle the pages directory contains any static links.

For example a page pages/about.md. Will produce a static page _site/pages/about/index.html. That can be called in web browser as http://localhost:4000/pages/about/.

Since I place my Jekyll files in my Github repository, I put README.md beside index.html.

I also put common web files in root directory. So this is all.

.
├── favicon.ico
├── feed.xml
├── index.html
├── README.md
└── sitemap.xml

Permalinks

The official guidance is here

• https://jekyllrb.com/docs/permalinks/

The _posts directory contain all your posts. For each post, you can set a category, in frontmatter.

For example a post 2014-03-26-wireless-command-line.markdown that contain below formatter.

date:   2014-03-13 18:32:15 +0700
categories: system

Will produce a static page _site/system/2014/03/13/wireless-command-line.html. That can be called in web browser as http://localhost:4000/system/2014/03/13/wireless-command-line.html.

Each blogger has different categories, mine are design, desktop, opensource, system, webdev.

Now let’s see what’s happened in _site.

Source:

• github.com/epsi-rns/dotfiles/…/_posts

pages Directory

What’s in here? Static page of course. About, Searching, Blog Archive, Index. Just use your imagination.

The transformation on the _site should be clear one to one, exactly the same as the original one. Except that I’m using jekyll-paginate that transform links in pages/index.html into some _site/pages/blog-n.html

Source:

• github.com/epsi-rns/dotfiles/…/pages

_posts Directory

You can put all your posts in one single _posts directory. But as soon as your blog growing to 200 posts, it is going to be hard to find a particular post, when they all mixed in only one place.

You need to make folder to group some posts together. Jekyll will loop over all _posts directories to find all your post. So make yourself at home, rearrange your furniture as you wish.

I choose to have those folders by categories followed by year.

. _posts/
├── alumni
├── design
│   ├── 2015
│   └── 2016
├── desktop
│   ├── 2014
│   ├── 2015
│   └── 2016
│       ├── 2016-03-26-xmonad-config.markdown
│       ├── 2016-07-06-awesome-structure.markdown
│       ├── 2016-07-13-awesome-preparing.markdown
│       └── 2016-08-01-i3status-conky-lua-json.markdown
├── journal
├── opensource
│   ├── 2014
│   ├── 2015
│   └── 2016
├── system
│   ├── 2014
│   ├── 2015
│   └── 2016
└── webdev
    ├── 2016-05-14-jekyll-blog-overview.markdown
    ├── 2016-06-22-jekyll-arch-install.markdown
    └── 2016-06-23-jekyll-debian-install.markdown

And it would be transformed just like this.

. _site/desktop/2016
├── 03
│   └── 26
│       └── xmonad-config.html
├── 07
│   ├── 06
│   │   └── awesome-structure.html
│   └── 13
│       └── awesome-preparing.html
└── 08
    └── 01
        └── i3status-conky-lua-json.html

And instantly, those can be called in your favorite web browser.

• http://localhost:4000/desktop/2016/03/26/xmonad-config.html.

• http://localhost:4000/desktop/2016/07/06/awesome-structure.html.

• http://localhost:4000/desktop/2016/07/13/awesome-preparing.html.

• http://localhost:4000/desktop/2016/08/01/i3status-conky-lua-json.html.

Source:

• github.com/epsi-rns/dotfiles/…/_posts

Just like that. Very simple. So common for people working with computers. But I have seen professionals failed to tidy their own data in their firm.

assets Directory

Overview.

This is completely yours to arrange.

. assets
├── posts
│   ├── alumni
│   ├── design
│   ├── desktop
│   ├── journal
│   ├── opensource
│   ├── system
│   └── webdev
├── site
│   ├── images
│   └── js
├── themes
│   ├── default
│   └── oriclone
└── vendors
    ├── bootstrap
    ├── font-awesome
    ├── jquery
    └── lunr

assets/posts

Respectively I also create an posts directory inside assets directory. This directory contain static images related to each post.

. assets/posts
├── alumni
├── design
├── desktop
│   ├── 2014
│   │   ├── 04
│   │   ├── 05
│   │   ├── 10
│   │   ├── 11
│   │   └── 12
│   ├── 2015
│   │   └── 02
│   └── 2016
│       ├── 03
│       │   ├── modularized-xmonad-1.png
│       │   └── modularized-xmonad-2.png
│       ├── 07
│       │   ├── awesome-modularized-code-binding.png
│       │   ├── awesome-modularized-code-main.png
│       │   ├── awesome-modularized-stacked.png
│       │   ├── awesome-refactoring-manjaro.png
│       │   └── awesome-refactoring-syawal.png
│       └── 08
│           ├── i3-conky-1-old.png
│           ├── i3-conky-2-lua.png
│           ├── i3-conky-3-json.png
│           ├── i3-conky-lua-json-bottom.png
│           └── i3-conky-lua-json-top.png
├── journal
├── opensource
├── system
└── webdev

And later, you attach image from any of your markdown post.

![Modularized Awesome WM Code Main][image-ss-awesome-main]
![Modularized Awesome WM Code Module][image-ss-awesome-module]

[image-ss-awesome-main]: {{ site.url }}/assets/posts/desktop/2016/07/awesome-modularized-code-main.png
[image-ss-awesome-module]: {{ site.url }}/assets/posts/desktop/2016/07/awesome-modularized-code-binding.png

Source:

• github.com/epsi-rns/dotfiles/…/assets

_layout Directory

There is not much to talk about layout unless you are a hardcore site designer. This directory is containing your most html5 code.

. _layout
├── default.html
├── gen-sidemenu.html
├── page.html
├── page-sidemenu-jekyll.html
├── page-sidemenu-wm.html
├── post.html
├── post-sidemenu-jekyll.html
└── post-sidemenu-wm.html

Source:

• github.com/epsi-rns/dotfiles/…/_layouts

_include Directory

This one is not too boring as _layout directory, and it deserve its own article. But for now, I give you brief explanation. This directory is containing your most liquid code as part of your layout.

The idea is basically putting your own code, just to be not too crowded in one single directory.

And here is the details.

. _include
├── layout
│   ├── footer.html
│   ├── header.html
│   ├── head.html
│   └── sidemenu.html
├── page
│   └── sidebar.html
├── panel
│   ├── archives.html
│   ├── category.html
│   ├── recent-posts.html
│   ├── related-posts.html
│   └── tags.html
├── part
│   └── screenshot.html
├── post
│   ├── footer.html
│   ├── header.html
│   ├── pagination.html
│   ├── sidebar.html
│   └── time-elapsed.html
├── service
│   ├── disqus-comments.html
│   ├── google-adsense.html
│   ├── google-analytics.html
│   ├── muut-comments.html
│   └── yandex-metrica.html
├── opengraph.html
├── pagination-better.html
└── pagination.html

Source:

• github.com/epsi-rns/dotfiles/…/_includes

_sass Directory

This one is interesting, and it also deserve its own article. But for now, all I can do is giving you brief explanation.

This SASS directory contain your raw stylesheet before processed into CSS, called in assets/themes directory. This CSS Technology has become so complex, that it requires its own folders management.

Hypotethically, you can create your own switchable theme, with Jekyll. Although I have never seen anyone reach that far.

Source:

• github.com/epsi-rns/dotfiles/…/_sass

Happy Jekylling !