Jekyll In 15 Minutes

This post isn't going to go too much in depth about what Jekyll is, but more how to get going with it insanely quickly, however; Jekyll is a static-site generator. You give it Markdown, Liquid, HTML & CSS and it gives you a deployment ready site to upload to your server. Go read more on the site.

Fire up your command line

Now type these commands:

gem install jekyll

jekyll new my-awesome-site

cd my-awesome-site

jekyll serve --watch

# => Now browse to http://localhost:4000

What did we just do? Well, we installed Jekyll as a Ruby Gem (I should point out, that I have zero Ruby knowledge, so hopefully that gives you comfort...or you've stopped reading). We then created a new Jekyll site, put ourself into the newly created folder and then tell Jekyll to start up a lightweight webserver. We can then access the site on the URL above. We add on the --watch flag to tell Jekyll to re-generate the site on save of any of our source files. Super rad lovely workflow.

Folder structure

Jekyll creates you a folder called "_site" every time it compiles your source files. This folder will contain everything you need to upload to your server to display your site. You don't mess with these files or this folder. Do. Not. Mess.

Any folder you place in the root folder that is prefixed with an underscore, ie. "_layouts" is not copied to the "_site" folder on compilation. These folders are processed by Jekyll for output. If you create a folder called "img", for example, Jekyll will directly copy that folder to the "_site" folder, untouched.

If I create a folder called "archive", and create an index.html file inside, then it's automatically available at "myawesomesite.com/archive/".

Layouts

If I'm creating a blog, I would have two "layout" files inside a "_layouts" folder - default.html and post.html. Default.html will contain the HTML for my menu, footer, etc...basically everything but the dynamic content. My post.html will contain the wrapper HTML for my blog post's content, ie. post title, a "tweet this" link, Disqus code, etc...

In our layout files, we tell Jekyll where to place our dynamic content like so:

<div id="content">
	{{ content }}
</div>

or

<div class="post">
	{{ content }}
</div>

Posts

Sticking with the blog analogy, I'll need to be writing some posts sooner or later, so I'll create a "_posts" folder in the root. This will contain, in my case, several ".markdown" files, these are purely my post's content.

Front-matter

This is YAML front-matter block. It's where you stick all of the configuration for that particular page/post/content. It's placed at the top of a file and looks something like this:

---
layout: post

tags: post title: How to be cool on the internet ---

This will be processed by Jekyll during compilation, in this case, Jekyll will see that we've set the "layout" value to be "post", this tells Jekyll to use the post.html (we created earlier) as it's wrapper.

Going back to our "archive" page, we want to output links to all the "posts" in our "_posts" folder. We have the following HTML in our archive/index.html file:

<div id="blogposts">
	<ul class="entries">
	  {% for post in site.posts %}
	  <li>
	    <a href="{{ post.url }}">
	      <h3>{{ post.title }}</h3>
	    </a>
	    <span>{{ post.date }}</span>
	  </li>
	  {% endfor %}
	</ul>
</div>

What we've done above is loop around all the files in our "_posts" folder. Any variables we set in our front-matter, like we did above, can be accessed in these loops, ie. post.title will equal "How to be cool on the internet" when it's iterating the one above. More about front-matter.

And...the rest?

This is a nice point to wrap up. This isn't an exhaustive reference for Jekyll, when/if you need that, go to the very awesome docs. It's hopefully enough to get you to the point where you can get a blog up and running in ~20 mins!

If you want a complete Jekyll blog to clone and play around with, check out Musings, it's a very small blog that I run, but it's a nice Jekyll starting point.

Thanks to the 27 people on HelpMeWrite who wanted to read this!