If you want to build small page or blog and want to rely on Jekyll as a static site generator instead of using a fully fledged CMS, this article is for you.
Every once in a while I think about creating a personal website. Something I could maybe use as an online CV, portfolio or a little blog. For the beginning, nothing special. It would be easy to spin up a WordPress page, find a nice template and within short time it would be ready to use. But first of all, I think it would be an overkill to use a big CMS with all it’s crazy features for “just” a small page with few sites that don’t change often plus a bunch of blog posts.
That’s why I want to try a static site generator to see the alternatives. For this article, I chose Jekyll because it works well in combination with GitHub Pages.
Let’s start with the prerequisites and then create our own little website with Jekyll.
Install Ruby and Jekyll
To work with Jekyll, you need Ruby installed on your computer. If you don’t have it installed, have a look here for the install documentation.
Next, install Jekyll and also the bundler you need:
gem jekyll bundler
Create your page
Usually, a Jekyll site is created by executing jekyll new mypagename where mypagename is the name of the folder which is created during the process.
Congratulations, you just created your first site with Jekyll. Basically it consists of two pages (index.md and about.md) and a blog post.
Now assuming that we want to use that template, we may want to fill in some data to get rid of that placeholder texts. So open the _config.yaml and happy changing! (Note: If you change the values within the config file you will have to restart the serving process to see the changes)
Adding a new page to the site
Create a new file, e.g. Contact.md within the root directory of the page or any other subfolder (except _posts). The important part is to put a special header to the file. This header is called Front Matter.
--- layout: page title: Contact permalink: /contact/ ---
- Layout: Jekyll Themes have layouts which define how a certain page looks like. The default theme which we are using here has three of them: home, page and blog. While we won’t need home (it’s used for the index page) we want to use the other two for pages and blog entries.
- Title: You guessed it, whatever you put in here will be displayed as the title of that page. (Warning: This variable could be named different from template to template, since it is a custom variable)
- Permalink: This defines how the url to that page looks like.
There are some more Front Matter variables to use (e.g. published to hide posts). If you are interested what’s possible, have a look at the documentation.
Blog posts
Posts are located in the _posts directory. Also, you have to name the file in the pattern YEAR-MONTH-DAY-title.markup otherwise it will not be generated to your page. So let’s create a new file 2017-08-24-myfirstpost.md
Also here, put a Front Matter to the top of the file:
--- layout: post title: "My first blog post" date: 2017-08-24 21:55:55 +0200 ---
As you can see, you have to specify a date for your post. The example shows the full timestamp, but you can omit hours, minutes, seconds and the timezone as they are optional.
Warning: If you define a date in the future the post will not be generated to the page.
Like before when we created the Contact page, the content is written in Markdown.
Hosting
To get your site up and running you need to execute jekyll build and copy everything in your _site folder to your web space.
Wrapping up
Today we created a basic site with the static site generator Jekyll. I like how lightweight the page feels and how easy it is to just add something new. Okay, it’s also not that complicated to add a new page to a fully grown CMS, but hey — we just have to add a file and can focus on writing.
Initially I wanted to include how to host the Jekyll page on GitHub Pages to get rid of building the page on your own, but did not really work. I could find out that they only support a hand full themes, which do not include Minima which is Jekyll’s default theme. Changing the theme in the GitHub Pages settings afterwards did also not work, so I guess that needs a little bit of more work. This might be topic in a future article.
EDIT: Thanks to Vienna.html I can tell now that GitHub supports Jekyll’s default theme. To get it working, you just have to set theme to minima and it will work.