Building a Jekyll Website

So, you’ve built a few projects and are now looking for a place to display them that isn’t Github. This was me a few months back when I was job hunting, so I made the decision to build a simple portfolio website using Jekyll and thought I’d share how I did it.

What is Jekyll?

Jekyll is described as a ‘simple, blog aware, static site generator’. It’s basically a way to manage your blog or static website without the need for a database, which greatly improves the load time of the page. You can write your content in Markdown, edit the HTML/CSS, preview your site in it’s current state using the built-in development server and once you’re happy you can build and push your changes, which will then be reflected pretty much instantly on the live, production site. Plus, if you’re using Github, you can deploy and host your site for free using Github Pages.

Getting Started

I’ll assume if you’re reading this, that you have basic understanding of the command line and git, if not I’d suggest heading on over to Codecademy and whizzing through their Command Line and Git courses which will give you a good grounding in both.

First things first, go ahead and open up your terminal and type the following command to install Jekyll. If you’re familiar with Ruby, you’ll notice it’s a Ruby Gem. I should probably mention this now as well, but in order to use Jekyll you will need Ruby 2.0 or above, if you’re unsure you can always type ‘ruby -v’ in your terminal and see what current version you’re running on. For instructions on how to install Ruby, if you don’t have it, head over hear.

$ gem install jekyll bundler

Now you can use the ‘jekyll’ command to create your website. Navigate to a directory where you’d like to setup your site and then type the following command, this will generate a Jekyll site for you.

$ jekyll new nameofyoursite
$ cd nameofyoursite
$ bundle exec jekyll serve 
// Now browse to localhost:4000 to view a preview of your website.

Once the site is generated, navigate into the new project directory and use the ‘bundle exec jekyll serve’ to build a preview of your site on your local machine at localhost:4000. You can also just type ‘jekyll serve’ to achieve this. As Jekyll is written in Ruby it uses the Gemfile and Gemfile.lock to see the gem requirements of your site to make sure you have all the necessary dependancies, if your site doesn’t have a Gemfile, you can just use ‘jekyll serve’ to preview your site on your local development server.

You’ve now got a basic layout and all the ingredients to start writing your content and designing your website.

Now would be a good time to open up your favourite editor and begin looking around the directory to see how things are setup. In the project directory, you can simply type the following if you’re using Atom to open up the current directory you are in.

$ atom .

At this point, it’d be a good idea to setup git and link to your Github repo online.

$ git init
$ git add .
$ git remote add //(copy the link from Github once you create your repo online)
$ git push origin master

If you’re creating a website and constantly changing things, it may be an idea to checkout separate branches and merge them back into master when you’re happy. If you’re just creating blog posts and not doing too much editing, you should be fine to push directly to master, I’ll let you decide on whats best depending on your needs.

So, you’ll see you have a _posts folder, which will eventually contain all of your posts in a markdown format, you also have two pages: about and index. Index is the landing page however you’ll notice it just has text describing the layout as home. This is because with the default theme, the landing page is just a list of your posts, if you head to the ‘about’ page you can edit the content to describe the basics of your blog or website. The main file you’ll want to start editing, however, is the _config.yml file, this contains all the information about your site and allows you to add your social media links, email and other contact details.

Once you’ve edited these basic details you can create a new file in the _posts directory (you can just override the file currently in there and rename it to your first post) and begin writing some content. You’ll notice you’re able to tag each of your posts with a category and you can date each one as well, this helps when searching for them on your site. Once you’ve written some content you may want to have a quick look on the development server, if everything’s good you can go ahead and push your changes to master.

At this point, I’d also like to stress the importance of making regular git commits, especially if you’re in the process of updating a theme or making major changes as it keeps track of everything and allows you to revert back to a previous version if something goes wrong.

Taking the Website Live

The next bit would be to actually get this website live, I mentioned at the beginning if you’re using Github you can use Github Pages, which it’s so easy and simple to setup. Just head over to your repo, click the settings button on the far right of the navigation tab, scroll down until you see ‘Github Pages’. It’ll ask for a source, which you can choose as the ‘master branch’ and once this is done it’ll give you a URL to click, which will be your live site. Please note, from now on any changes pushed to the master branch will directly change the website, if you’re build breaks you’ll get an email and your site will go down. I’d suggest that the best thing to do before pushing to master, would be to run the ‘jekyll build’ command in your terminal.

$ jekyll build

If everything turns out fine without any error messages, you can push to the master branch with confidence that your site won’t break.

That’s it! Obviously there’s a lot more you can do such as changing themes, editing layouts and adding more content. In terms of themes, I usually head over to http://themes.jekyllrc.org/ and have a look at what is currently available, there’s usually a larger selection on there with some really nice portfolio specific themes available.

If you’re interested in what my site currently looks like, you can view it here. It’s quite simple, I’m still in the process of adding content as well as migrating it to AWS and distributing it using AWS CloudFront, which will be the topic of my next post.