september 6th
New York City 2017

#37 Changing to Jekyll

This post is about re-doing my personal website and blog. I got fed up of changing and “re-writing” 3 new html pages for every new post I wanted to make. Which eventually ended in me not really looking forward to writing a blog post, and therefore not really documenting my work that well. Which was a big mistake. So once I discovered jekyll and the way it works I decided to adapt both of them to this ruby engine.

At the same time I was trying to have everything in my VPS and deploying through Capistrano, which avoids having to do all the ftp procedures for any updates. But I ended up deciding on using GitHub Pages, as it is very easy to set up and even easier to update.

Ok. So you know why I wanted to change; basically an inefficient workflow to post anything on my blog or website, and a pain in the a$$ to format the text. But why Jekyll?, why not Wordpress (ew), or any other system that domain providers offer. The reason basically is “freedom”, to have the exact design I want but with the same advantages that others offer.

With Jekyll I could:

  • have the exact same web design as before.
  • prepare posts and revise them without having to use logins and being online.
  • use GitHub Pages, which is free.
  • have absolute control over every single aspect of my website.
  • very easy to make major changes to the whole website, without having to go through the pain that was search & replace.

Before you keep reading: This is a post that shows the process I followed and that worked for me, I work with Mac OS and there are chances that the installation and set up might be different in other systems, specially Windows. This is written with the intention of me internalize what I did and as a reminder of the process I followed to get there. This process works, the website you are in is “living” proof of it.

That said take into consideration that troubleshooting is an intrinsic part of the process and don’t expect to have absolutely everything explained here, I am taking the liberty of assuming that if you are going to follow this guide, you are at a similar level than the one I was before starting this process. That means that you know html, css, Javascript, and other programing languages at a level that is a substantiable amount above Basic. That you are at least kind of used to command line and you know what it does. And that you know what a local server is.

Last thing, this is the first post of this characteristics I write, so I would appreciate any kind of feedback. Either write a comment (If I did add the comment section…)
or send me an email!


This is the only job I had, besides learning Markdown, which we’ll talk about later.
I had to transform my static html page into all the different parts that make a Jekyll page come to life.
The bare essentials that one needs to have a jekyll set-up running. Are, first of all; Jekyll itself.

First step is fairly simple, install Jekyll in your machine: go to command line, and do the following

gem install jekyll bundler

If anything does not allow you to continue make sure you have things like ruby and bundler installed. Anything missing should be notified to you.

There’s some basic commands that Jekyll has and that you should know;
You can try them but nothing will really happen until you have appropriate content. Just learn what they are.

 jekyll serve 

Serve creates as local server that runs jekyll. What it does is picking up the content in the _directories (more on that briefly) and creates a _site directory that contains a static html page done from all the content you have set up. Said _site directory is read by the browser as a regular static html website.

 jekyll build 

Build does half of what serve does. It simply builds the static html pages, as said before; the _site directory. With that you can pick up the contents and upload them to your server via ftp. but thats the long and borring way, and unfortunately the way my portfolio works at the time of writing this. This means that once you have the content you need. You can just build the site.

So those two are pretty much the only commands you really need to know if you are building this site from scratch or thematising a existing website.


Jekyll builds the pages from pieces you set up. different html files that are arranged together to create the different layouts your website might have.
This directories you are gona use are 3: _includes, _layouts and _posts.


Includes have the following syntax

	{% include example.html %}

When using {%this%} you are making use of a tag which can’t resolve to text.
You use it for “functions” like if statements and others specific liquid tasks.
The other markup used in jelkyll is {{this}} which does resole to text, and is called output. (more on that later).

the _includes directory contains a series of html files that are snippets of a complete html page.

This means that we can go from this:

<!doctype html>
<html lang="en">

    <meta charset="utf-8">
    <title>The HTML5 Herald</title>
    <link rel="stylesheet" href="css/styles.css?v=1.0">
    <script src="js/scripts.js"></script>



      <p> content</p>




To this:

<!doctype html>
<html lang="en">

  {% include head.html%} 


    {% include header.html%}

    {% include footer.html%}



What has been done here is that three new files have been created with the code for <head>, <header> and <footer>

This allows us to only worry about one file when doing site-wide changes to this specific sections of the code. It’s a problem when trying to do a small change and being forced to use search and replace and never being sure if everything works.

The other addition is {{content}} to the area where the main content goes.
This is where the html code goes when is generated by jekyll from the .md files we’ll have in _posts.


Layouts are regular html files with the same structure shown above. This basically are different structures you want your site’s pages to have. They are called from de _posts’ content where the tag “layout:” is used.


links that either, you should check out, or have been mentioned in this post


Please, tell me how good or bad this post was. And comment on anything that comes up in that beautiful brain of yours.