I wanted to switch from WordPress to Jekyll on this blog. I first started using WordPress on May 17, 2006 on another blog and have since used it regularly, and for a period of time between 2009 and 2011 I posted multiple times a day. Since starting this new blog several weeks ago I came across a handful of sites that use Jekyll. After a bit of study I decided it was time to test it out. With this being a fairly simple blog that is mostly lots of text and sometimes an image or 2, I decided it would be a good fit, or at least I think it will be a good fit.
What I will Cover
I will be walking you through how I installed Jekyll on my iMac. I will also be explaining what does what in Jekyll although it will be a very basic tutorial on how to publish a post and test the site locally.
What I won’t cover is more in-depth things such as permalinks, themes etc… although I will at a later date.
Requirements
The requirements are extremely basic to run a Jekyll website. Jekyll is installed locally. You write your content locally in Markdown. You build the site. It spits out a static website in html and you then upload that to a web server of your choice. There is no database and no need for anything fancy to be installed on the server.
The Process
After finally getting to grips with how Jekyll works I decided that I need to create a new workflow to make the transition worth it. In WordPress it’s quite simple. I can log in from any browser, click New Post, write, publish, and be done. With Jekyll there’s a few more steps involved that all seemed a little complicated when I first came across them. Now that I have Jekyll installed I actually find it’s quite simple to use and quick to update.
What I am Using
In this post today I want to just show what I am using locally. In my next post I’ll write about what I am doing to get that content to a server and where that server is located.
Locally I use the following:
- Jekyll (as expected). This powers the website.
- iA Writer. Used to write my content. I use this on macOS and iOS. You can use any text editor that you want. I just like this particular one at the moment. If I want to switch to another, that’s no problem because markdown is just text.
- DropBox. I store my blog in a DropBox folder as it works well for syncing to my iOS devices and my MacBook.
- Git. I use Git for tracking the changes made. My plan is to commit each successful build and send to GitHub. That way, if I am making large modifications and mess it up, I can just step back and start from where the site was working previously.
I might consider TextExpander in the future which I think will be helpful for some common text such as the front matter, code snippets, etc… but I haven’t ever used it and don’t even know if it’s compatible with iA Writer. It isn’t too important to me in the first stages.
Installing Jekyll
The instructions are simple to follow on the Jekyll website. I just followed the quick start instructions on the main page. To do that, open Terminal and navigate to the folder where you want to add your new blog to. In my case I entered
cd dropbox
cd apps
Install Jekyll by entering (note that this command isn’t related to the ones above… you can install Jekyll as soon as you open terminal).
gem install jekyll bundler
Next you generate a new site by entering:
jekyll new websitename
In my case I called it MatthewNewillBlog so that I can identify it.
When this is done it runs through the process of building the site. When done:
cd matthewnewillblog
To test it’s working enter:
bundle exec jekyll serve
Then open a web browser and go to http://localhost:4000
You will see a basic website running now.
Configuring Jekyll
The main configuration file for Jekyll is called _config.yml found in the root of the Jekyll install. Open this with your favourite text editor. To do this I opened the finder, navigated to my Jekyll install, opened the file with Textastic.
There are a few items to modify in here. You can give the site a title, an email, a description, as well as a URL. There are also some build settings which I haven’t modified just yet.
After making the changes, save.
To see those changes we need to rebuild the site. The command for that is (make sure you ctrl-c if the server is still running):
jekyll build
When it completes you can start up the server again with:
bundle exec jekyll serve
When the server is started, reload the website. You should see your changes reflected on the page.
Structure
The basic structure of Jekyll is that you have a _posts folder and a _site folder. _posts is where you content is put that you want to go live on your site. The _site folder is generated automatically when you used the ‘jekyll build’ command. The contents of this folder are what you upload to your webserver after building the site.
Creating a New Post
Creating a new post can either be done in a _drafts folder, or you can create it in the _posts folder. If you use the _posts folder, just be aware that you might end up publishing a half baked post if you do a rebuild and sync the _site folder, so be careful with that option. For example, you might start working on a post, add the front matter, forget about the half finished post and leave it there and create something new. On your next build you may upload half a post that wasn’t intended for the blog. Be careful!
Open your text editor and create a new file. The filename needs to be in a specific format which is:
YEAR-MONTH-DAY-post-title.md
If I want to publish a post with todays date that would become (my-post-title is what I want to call it. I guess that would be classed as the post slug in WordPress):
2017-01-06-my-post-title.md
When the text file is created you then need to create front matter in YAML as a block at the top. The front matter block for this post looks like this:
layout: post
title: "Switching from WordPress to Jekyll – First Steps"
comments: false
date: 2017-01-06 11:12:32
It starts and ends with 3 dashes. The in between parts provide some needed information such as it uses a post layout, has no comments, and has a title. The date/time is in the following format:
YYYY-MM-DD HH:MM:SS +/-TTTT
The time and offset are optional. If you post a few times a day it could be worth specifying the time. I do just because it’s easy enough to do although I don’t use an offset.
More details about Front Matter can be found here.
When the front matter is in place, you can now write your blog post. You write in markdown or HTML. I am fairly new to markdown so won’t try give a tutorial on how it works. All I am doing is starting with the basics such as creating links and using bold text. Because my previous posts had some HTML for images, I just left those as they were, but there is syntax in markdown to specify images. You can read about all of what markdown can do over here.
Publishing your new Post
Now that your content is written and you are ready to publish, it’s time to test.
If your post isn’t already in the _posts folder, move it there.
In terminal navigate to the new blog folder.
Run the following command:
jekyll build // Note that you probably don’t need to ctrl+c from the server as it seems to build automatically on the fly… but if you don’t see changes then I suggest rebuilding.
Followed by:
bundle exec jekyll serve
When you load up the website at localhost:4000 you should now see your new post. Note that you will also see another post which was automatically put there when you installed Jekyll. To remove that, just delete it from the _posts folder and rebuild your site. I hope that by testing doing this that you will see how easy it is to manage your Jekyll install.
In the next post I’ll explain how the theme can be changed and how you can change the structure of your website. After we have the website looking good on the local server I’ll move on to explain how to put the site on to a webserver.