Website Part 2: Efficient & Productive Website Creation with Jekyll
In the previous article, I talked about how our team switched to using Github Pages for hosting our website. Now that I had a repo set up, it was time to actually make the website. Now, copying over the old site was not directly an option — it was written in Angular, and Github Pages is limited to static sites (no server-side code). Even though Angular is able to be compiled to a static site, that leaves database access stuff (I was using Google Firebase to store images and site content) open to anyone who opens the developer tools and reads our javascript :). Furthermore, Angular was quite a bit of overhead to develop — it’s great for performant Single-Page Applications (web apps that don’t reload when you switch between pages) — but I was spending too much time messing around with Node.js and not enough time writing the content of the website. So I decided to scrap Angular, Node, Firebase, the whole set, and start clean with the old-school way: static W3C.
Yes, that’s right — just HTML5, CSS3, and ECMAScript 2015 (JS). Wait, don’t go away — it’s not as bad as you might think. The modern web suite is fast, easy(ish) to use and more powerful than you might think! Plus, we can make our life a little easier with CSS extensions, stylekits, templates, and more. In this article, I’ll cover templating with Jekyll.
So I was browsing https://pages.github.com/ , and at the bottom I came across something I had never seen before — Jekyll. Github Pages mentioned it as “Blogging with Jekyll”, so I didn’t assume that it would be useful for us, but I decided to check it out anyway. And I’m glad I did.
Jekyll’s web site is at https://jekyllrb.com/. This article will cover the basics of Jekyll, but everything I mention here (and much more) is covered in the documentation at the Jekyll website. So let’s get started!
Jekyll is written in ruby, so you’ll have to install ruby on your system, as well as the Jekyll gem (instructions are covered in more detail on their website, so please check there.) Once you have installed it, make a new directory where ever you want to store your website source, and change to it. Edit a new file index.html in your editor of choice, and paste in the following code:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Home</title>
</head>
<body>
<h1>Hello, World!</h1>
</body>
</html>This “Hello World” source code is a proof of concept — we’ll add stuff to it in a little bit. As I mentioned earlier, Jekyll supports templating — as a result, it is built to process metadata and supersets/extensions of regular web languages and transpile them into regular code. The above example doesn’t use any of these extensions, so you can open this file up in your browser to see the title “Hello, World!” displayed in a big, serif font. However, since we will soon start using non-standard web code to write the website more efficiently, let’s build the project properly. Open a terminal prompt in the directory where you store index.html and enter: jekyll serve. This will compile the code (in this case not changing anything), and serve it as a local webserver, only accessible on your machine. Remember to keep the command running — don’t Ctrl-C it or close the window. It is best to move that terminal window off to the side, and open another one/another tab for your other work. You can also fork the process/move it to background, but this might make it harder to stop in the future.
Liquid
So now let’s make use of the templating features! The first “metadata” we will add makes use of Jekyll’s Liquid syntax, which allows manipulating data inside your static markup. For example, replace the contents of the body in index.html with <h1>{{ "Hello, World!" }}</h1>. As you might recall from other programming languages, the double quotes refer to a string of characters. The curly braces allow Jekyll to parse operations inside and substitute the result in the final markup. If you reload your site, nothing will change — it shouldn’t have, since the same string is being displayed as before. Now, replace the curly braces with {{ "Hello, World!" | downcase }}. Now reload — you should see the string hello, world!. The pipe + downcase is a filter, one of the many operations that Liquid can perform.
Front Matter
Jekyll also makes heavy use of Front Matter, which is basically some miscellaneous data in YAML format stored at the top of a file. You can use front matter by inserting 2 lines of --- at the top of your file, and insert the front matter between those lines. Let’s add some basic data. At the top of index.html, add the following code:
---
title: Jekyll is Awesome!
---<!doctype html>
...
Next, replace the title element with <title>{{ page.title }}</title>. By doing so, we are accessing the title variable from the front matter and plugging it into the title element. You can replace the other raw text on your page with front matter variables in a similar fashion. But why would you want to do this? It seems like extra code for no reason, right? Well, there are 2 main reasons to use front matter variables:
- When you want to edit some content on your site, variables make it easy to edit the text/media at the top of the page, as opposed to scrolling through potentially gargantuan markup files.
- If you are using the same text multiple times, it is easy to make typos. With variables, you can define the text once and plug it in in multiple places.
That’s the basics of Jekyll — I’ll cover some slightly more advanced topics in the next article.
