Jekyll is the most popular static site generator, it has few basic concepts to understand how it works.


Jekyll is, at its core, a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or a series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed in the layout, and more.

How Jekyll generates a site

graph TB defaultconf["Initialize a new Site with default configuration"] defaultconf==>read["Read Site data from disk and load it into internal data structures"] read==> customconf["Read custom _config.yml, overwrite default values"] customconf==>generate["Run each of the Generators"] generate==>render["Render the site to the destination folder"] render==>cleanup["Remove orphaned files and empty directories in destination"] cleanup==>write["Write static files, pages, and posts"]

Jekyll Post and Pages filenames works as urls slugs.


Content can be published in Jekyll in several ways:

Article Metadata

Each Post is composed by metadata and content. This metadata is called the Front Matter and it needs to be located at the top of each post between the special characters --- to assign custom variables to the current post.

The Front Matter is the piece of code that tell Jekyll to process a page or post in a special way, where you can change the layout, language or more configurations that if not specified they just took the default settings of config.yml. .


layout: post
title: My cool blog

It has two requirements:

  • It must be at the beginning of the file
  • It must be in YAML format

Predefined global variables

Predefined global that can be specified in the front matter of a post or page.

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.
If you need your processed blog post URLs to be something other than the site-wide style (default /year/month/day/title.html), then you can set this variable and it will be used as the final URL.
Set to false if you don’t want a specific post to show up when the site is generated.


Formatting syntax

The most common formatting syntax used in posts and pages are:

Syntax highlighting

By default Jekyll uses Rouge as its syntax highlter and is compatible with Pygments highlighter.

Templating system

Jekyll uses the Liquid template engine:

The template files processed by Liquid uses three main concepts to generate the valid HTML files:


  • Local instance with bundle
$ bundle exec jekyll serve --watch --drafts


Marcelo Canina
I'm Marcelo Canina, a developer from Uruguay. I build websites and web-based applications from the ground up and share what I learn here.