Log(n) Engineering

Using Jekyll

Agenda

Let’s assume this is going to be some kind of «talk» or «conference session» and everyone reading this is actually «hearing» it from a presenter.

Here’s the agenda for today’s talk:

  • Jekyll : What is it? How do you eat it? 👹
  • Octopress: 🐙📠? Is it 🍣?
  • This sounds hard to process… 👀
  • How to use it for our nefarious purposes 👺
  • Deploying the blog? 😱
  • Why does every single item has an emoji❓

History

http://media2.giphy.com/media/1EHUBTElxvlE4/giphy.gif

Let’s start with a little bit of history because; who doesn’t LOVE some history!???… hello… hello!??? is thing on 🎤??

Jekyll

Ok; let’s start with a quote here from Jekyll’s website:

Jekyll is a simple, blog-aware, static site generator.

Everyone clear right? OK, into the next point in the agenda… no? OK.

What does that even mean? Basically it means that instead of writing our own blog using obscure HTML, HTML5, CSS and perhaps some GSS(don’t know that GSS is? please do yourself a favor and read about it; we’ll wait… yes; I PROMISE!!) we’ll be using good «old» fashiond Markdown, Liquid (although we won’t care about this) to write our blog posts and then Jekyll along with Octopress will do the heavy lifting of rendering a complete, ready-to publish static website that among a BUNCH of benefits will also let us accept pull requests for our blog content (because we all know those pesky typos keep finding their way to our beloved posts 🐛)

Octopress 🐙 📠

First of all yes… 📠 <– that’s a fax machine… there’s no «press» or «printer» emoji… deal with it.

Second…

What the heck is Octopress??

The easiest way to think about Octopress is to think of it as a blogging framework.

Basically it runs «above» Jekyll and automates most of the boring tasks that otherwise we would have to code by hand on the terminal 💻 and instead we just run a couple of rake commands.

This sounds hard to process

  1. First of all let me tell you something; is not hard at all. In fact is simpler than most blogging options (well; not true but let me get to the nitty gritty deatils of this statement before trying to lynch me here) because it gives us A LOT more power over the content; its generation and everything we need to know to actually grab the blog and make it ours.

  2. Now; even if everything I just told you above wasn’t true; I was sooooo nice that went to the trouble of configuring the blog with Jekyll and Octopress with a custom template and pushed everything to Github so you people only need to follow the steps on this post. Am I not GREAT!? 🎉

How to use it for our nefarious purposes

http://media4.giphy.com/media/JwjUmrdoRdt7O/giphy.gif

Like I just explained this repo comes fully configured and requires minimal effort from your part to start generating content; because we wanted YOU to spend time generating content and not wasting it figuring out how to tie everything together.

First of all go and clone this repo somewhere (again; I’ll wait for you right here…) with the following commands:

1
2
git clone github.com/lognllc/lognllc.github.io lognSUPERAWESOMEBLOG
pushd lognSUPERAWESOMEBLOG

Notice that we are automatically on a branch named source; this is because the blog will be living in master; just like you read it. master will hold the actual blog and source will hold the content used to generate it. I know it might sound confusing but bear with me just a little longer.


Now that we have the code downloaded AND we are inside the lognSUPERAWESOMEBLOG folder we can proceed to run a ONCE IN A LIFETIME (you’ll never read a better offer) command:

1
make

This will make sure that you have bundler install and that you have all the required gems and the latest version of them (we don’t want you to write using old stuff like 📝 do we???)

And that’s it; you have a fully configured blog «engine» ready for your amazing content.

Generating posts/pages

Let’s get a little nerdy in here 👓 and let it out in the open; a page is different than a post.

How so you ask?

Easy; a blog post is something like this you are reading right now while a «page» might be something like an «about» or «contact», etc. Posts are supposedly going to be a living thing that keeps growing and needs an archive whilst pages are mostly «frozen» and we would need just a few in our blog for the «pinned» content that needs to be here and there and everywhere.

Now; back to the topic. How do you start a «post»?

Easy, just be sure you are on the «source» branch and on the root of the folder and run the following command:

1
rake new_post

That’s it; Octopress then will ask you for a name for the post and a new .markdown file will be added to the _posts folder for you to fill in with those juicy ideas later.

Same thing goes for «pages» except that the command is:

1
rake new_page

And obviously the new file will be in the root . folder.

What’s that weird syntax above my post?? 😵

http://media2.giphy.com/media/C1ODiCUL8VO9O/giphy.gif

Above every new post and page there’s some predefined syntax called YAML Front Matter which pretty much explains the content to the renderer so that it can smartly generate the site accordingly.

There are some defaults defined in the _config.yml file of the repo but the configuration in each post takes precedence over the defaults.

The Front Matter syntax looks like this:

1
2
3
4
5
6
7
8
9
10
---
layout: post
title: "Using Jekyll"
date: 2015-06-11 17:10:31 -0600
comments: false
categories: how-to blog post guide
author: Esteban Torres
socialHandle: <a href="http://twitter.com/esttorhe">@esttorhe</a>
published: false
---

It’s pretty self explanatory:

  • You define the type of layout that will be used when generating the static site.
  • The comments flag for when we decide to configure a Disqus or some other sort of commenting platform.
  • The author is pretty important; otherwise it will be signed as «Log(n) Employees» which is pretty vague.
  • published: Another BIG one; if set to false no matter how many times you deploy it will never hit public. Useful if you are working on multiple posts (god forbids I find out you are doing this on the same branch 😒) and for some reason you need to send EVERYTHING. With this flag you can rest assure the post won’t hit public until set to true.
  • And to demonstrate the power of this blogging platform; I took the liberty of adding the socialHandle attribute. What it does is that next to the author it will write the following:

{{ author }} - {{ socialHandle }}

As you can see socialHandle can take mostly anything (I added a link to my twitter handle) and I added it to show you how we can modify the blog and also to help the authors generate a digital presence to the world.

The default value is a link to Log(n)’s website:

1
2
socialHandle:
    <a href="http://logn.co">logn.co</a>

Now What!?

OK; you are done with the greates blog post in the history of blog posts; but… how does it look?

Rest easy my friend; just head to your trusty friend the terminal and write the following:

1
rake test

This will tell Octopress to clean the folders, generate them and start a preview of the blog; this will boot a localhost server running on port 4000; meaning that if you open your browser here: localhost:4000 after successfully running the above command it will load the blog with your current posts.

Deploying the blog?

Things here get a little interesting; you people will only have the option but the truth is there are many ways to deploy this blog.

There’s rsync, push, root_directory/subdirectory, github_pages and probably a bunch I don’t even know about.

This blog comes «pre configured» to use push. And the heck does that even mean?

Well… it means that with a simple command:

1
2
rake generate
rake deploy

The blog get’s generated and deployed!! 🎉


Note: it is REALLY important to run rake generate before attempting to do a deploy. More so if we just cloned the repository because this means that our public folder is non existent; and if it’s not «freshly» cloned this could mean we would be pushing «stale» data.


Octopress will clean our public folder, will then configure it as a git repo of the blog pointign to master, then it generates it again compiling the sass files and stylesheets into our static website and finally will make a commit and push to master which will in the end make the static website visible and available to the world.

http://media2.giphy.com/media/InPQz9S7jcqUo/giphy.gif

BUT

http://media4.giphy.com/media/WPmvJaZTGZ2N2/giphy.gif

Don’t you hate it when there’s a «but»!? And the worst… there’s ALWAYS a «but».

This blog will work as a blend between Gitflow and Pull Requests. This means that our master branch will be the same as in Gitflow, the latest stable version.

Our development branch will be… yes; you guessed correctly… source.

And our «feature» branches will be the posts (please when creating a new post name the branch as post/name_of_your_post) and that’s as far as the Gitflow similarity goes because this is where we transition to the PR system. Every time you finish writing a blog post that you know will change the way every computer science engineer will see the world you’ll have to publish your post branch and then create a pull request to the source repository and the source branch.

Why?

Well; we would like to have curated content and also do an editor job and «pre check» that there are no typos, grammar or syntax issues with the writing before hitting pubic 👀 to deliver the best content we can make to the rest of the world.

Once the PR get’s merged back to source whoever approves the merge will be in charge of running the generate and deploy tasks and check that everything went as smoothly as possible.


Link to the presentation:

As you might have guessed this post was also a presentation given at Log(n)’s offices by Esteban Torres - @esttorhe and the source of the presentation can be found here; if you don’t like reading slides as markdown feel free to read them @ SpeakerDeck.

http://media3.giphy.com/media/RTXqWOJ3hDkcg/giphy.gif